ROCKITPLAY API
  1. Deployments
ROCKITPLAY API
  • ROCKIT Edge - Admin API
    • Minimal Tests
      • ping
      • submit test task
    • Admin Edge Organizations
      • Create Organization
      • Delete Organization
  • ROCKIT Edge - Backend API
    • Backend Edge Organizations
      • Create Organization
      • Delete Organization
    • Authentication
      • user login
      • authentication
    • Account Management
      • get user details
      • list users
      • Modify user
      • delete users
      • Create User / Create Machine User
    • Deployments
      • Creating Deployments
        POST
      • Get Deployments
        GET
      • Get Deployment Details
        GET
      • Modify Deployment
        PATCH
      • Deleting Deployments
        DELETE
    • Apps
      • Creating Apps
      • Import native builds
      • App Details
      • List Apps
      • patch app
      • Delete Apps
    • Triggers
      • Process Traces
      • Retry Task
    • Tasks
      • Listing Tasks
      • Task Details
      • Acknowledge Warning / Expire Task
    • Subscriptions
      • Subscribe
      • List Subscriptions
      • Unsubscribe
    • Roles
      • List Roles
      • Create Role
      • Patch Role
      • Role Details
      • Delete Roles
  • Changelog
    • Changelog
  1. Deployments

Creating Deployments

POST
https://Example-Server.com/be/v1/deployments
Last modified:2025-05-08 12:00:04
This endpoint registers a new ROCKIT Edge deployment. A deployment must contain an origin configuration describing where the generated ROCKIT Images and ROCKIT Patches should be published.
It may also contain a download authentication group in case ROCKIT Edge should also handle the CDN download authentication, for example for using the ROCKIT StreamInstaller.

File structure on deployment:#

The generated file structure can be obtained from GET /be/v1/apps. It returns all relevant information to access ROCKIT images via an dxfName as well as the available patches in an array fromBuildId-toBuildId. ROCKITPLAY deploys the files according to the following file structure to your origin:
DxF path: originPrefix/dxf/orgName/appName/iCurBuild/dxfName/*
Patch path: originPrefix/pat/orgName/appName/toBuildId/fromBuildId/*
with
originPrefix: is defined when you call POST /be/v1/deployments
orgName: "is defined when creating an organization"
appName: is defined when you call POST /be/v1/apps
dxfName, fromBuildId-toBuildId, iCurBuild: can be obtained from GET /be/v1/apps
in paths buildIds are masked as 4 digit number, e.g. iCurBuild = 1 becomes 0001 in path

Important:#

If incorrect credentials are used when creating a deployment, the deployment will still be created without errors. However, this issue will surface later during the app creation and build import process (e.g., with POST /be/v1/apps and POST /be/v1/builds).
Common Problem Indicators:
If an app tries to deploy but cannot, it will enter an error state.
Checking GET /be/v1/apps will show that the app is in an error state.
GET /be/v1/tasks can be used to inspect which task failed.
Solution:
If an app fails to deploy due to incorrect credentials or deployment issues, you can resolve it in one of the following ways:
1.
Update the Deployment Credentials & Retry the Task
Use PATCH /deployments to update the deployment with the correct credentials.
Use Retry Task to trigger the failed task again.
If the task now succeeds, the app will no longer be in an error state.
2.
Deregister the Faulty Deployment & Retry the Task
Deregister the incorrect deployment(s) from the app with PATCH /apps.
Use Retry Task to redeploy the app to all correctly registered deployments.
If successful, the app will no longer be in an error state.

Additional Notes#

In order that AWS S3 buckets work correctly, please make sure the hostname does
not contain the bucket name and contains the region, i.e.
s3.us-east-1.amazonaws.com.
Currently no other region than us-east-1 is supported for the original AWS S3.

Required Permissions#

deployments.create
See Roles for more details.

Request

Header Params
x-rockit-beauth-token
string 
optional
ROCKIT Edge backend authentication token (POST /be/v1/auth) or API key (POST /be/v1/apikeys)
Mutually excluded with x-rockit-api-key.
Example:
{{_edge_org_admin_beauth_token}}
x-rockit-orgname
string 
optional
Unique and immutable organization identifier obtained from the ROCKIT Edge administrator.
Requires x-rockit-username and x-rockit-api-key.
Example:
{{EDGE_ORG_NAME}}
x-rockit-username
string 
optional
Unique and immutable username which is accociated with the apikey.
Requires x-rockit-orgname and x-rockit-api-key.
Example:
adminPrincipal
x-rockit-api-key
string 
optional
Unique and immutable apikey which is accociated with an machine user.
Mutually excluded with x-rockit-beauth-token. Requires x-rockit-username and x-rockit-orgname.
Example:
{{_adminPrincipal_apiKey}}
Body Params application/json
name
string 
required
Match pattern:
/^[A-Za-z0-9_]{2,50}$/
label
string 
required
origin
object 
required
s3
object 
required
dlAuth
object 
required
gcore
object 
required
Example
{
  "name": "gcore",
  "label": "Gcore Object Storage / Gcore CDN",
  "origin": {
    "s3": {
      "hostname": "{{EDGE_ORIGIN_GCORE_HOSTNAME}}",
      "accessKey": "{{EDGE_ORIGIN_GCORE_ACCESS_KEY}}",
      "secretKey": "{{EDGE_ORIGIN_GCORE_SECRET_KEY}}",
      "location": "{{EDGE_ORIGIN_GCORE_LOCATION}}",
      "bucket": "{{EDGE_ORIGIN_GCORE_BUCKET}}",
      "prefix": "{{EDGE_ORIGIN_GCORE_PREFIX}}"
    }
  },
  "dlAuth": {
    "gcore": {
      "baseUrl": "{{EDGE_ORIGIN_GCORE_BASE_URL}}",
      "secureToken": "{{EDGE_ORIGIN_GCORE_SECURE_TOKEN}}",
      "bucket": "{{EDGE_ORIGIN_GCORE_BUCKET}}",
      "prefix": "{{EDGE_ORIGIN_GCORE_PREFIX}}"
    }
  }
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://Example-Server.com/be/v1/deployments' \
--header 'x-rockit-beauth-token: eyjhvcIhvds;huVODV...' \
--header 'x-rockit-orgname: ExampleOrg' \
--header 'x-rockit-username: adminPrincipal' \
--header 'x-rockit-api-key: {{_adminPrincipal_apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name" : "gcore",
    "label" : "Gcore Object Storage / Gcore CDN",
    "origin" : {
        "s3" : {
            "hostname" : "{{EDGE_ORIGIN_GCORE_HOSTNAME}}",
            "accessKey": "{{EDGE_ORIGIN_GCORE_ACCESS_KEY}}",
            "secretKey": "{{EDGE_ORIGIN_GCORE_SECRET_KEY}}",
            "location" : "{{EDGE_ORIGIN_GCORE_LOCATION}}",
            "bucket"   : "{{EDGE_ORIGIN_GCORE_BUCKET}}",
            "prefix"   : "{{EDGE_ORIGIN_GCORE_PREFIX}}"
        }
    },
    "dlAuth": {
        "gcore": {
            "baseUrl"    : "{{EDGE_ORIGIN_GCORE_BASE_URL}}",
            "secureToken": "{{EDGE_ORIGIN_GCORE_SECURE_TOKEN}}",
            "bucket"     : "{{EDGE_ORIGIN_GCORE_BUCKET}}",
            "prefix"     : "{{EDGE_ORIGIN_GCORE_PREFIX}}"
        }
    }
}'

Responses

🟢200200: success
application/json
Body
status
string 
required
A string that confirms the deployment creation was successful.
message
string 
required
A confirmation message (e.g., "deployment created") indicating that the new deployment has been registered successfully.
Example
{
  "status": "success",
  "message": "deployment created"
}
🟠400400: invalid-param
🟠401Unauthorized
🟠409409: item-exists
Previous
Deployments
Next
Get Deployments
Built with