ROCKITPLAY API
  1. Apps
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
      • Get Deployments
      • Get Deployment Details
      • Modify Deployment
      • Deleting Deployments
    • Apps
      • Creating Apps
        POST
      • Import native builds
        POST
      • App Details
        GET
      • List Apps
        GET
      • patch app
        PATCH
      • Delete Apps
        DELETE
    • 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. Apps

Import native builds

POST
https://Example-Server.com/be/v1/builds
Last modified:2025-05-08 12:00:04
This endpoint adds a new game build to an existing app. Once imported it will automatically generate
a new ROCKIT Image
new ROCKIT Patches if the uploaded game build is not the initial one.
There are two upload modes supported:
1.
ROCKIT Edge Download Request.
2.
Client Upload.
Both methods are described below.

File Format#

The game build is expected as an uncompressed tarball native-build.tar. The generation can be done as follows:
Operating SystemTool
Linuxcd path/to/gamedir
tar cvf /var/tmp/native-build.tar .
Windowsin PowerShell:
cd path\\to\\gamedir
tar -cvf C:\\temp\\native-build.tar .

ROCKIT Edge Download Request#

If a download URL is provided in the request body (url), ROCKIT Edge will download the native game build automatically. If the optional body request parameter size is given, a simple file size check is executed after the download has concluded.
This is the preferred method of importing a native build to ROCKIT Edge. The provided URL could be a signed URL with a short lifetime.

Client Upload#

An alternative to the ROCKIT Edge Download Request is the Client Upload method. By invoking this endpoint without providing the url body request parameter a temporary upload URL is returned in the response body. Upload the file to this URL using PUT.
This method can be applied if there is no publically available URL which ROCKIT Edge could download from.

Bash#

C/C++#

Python#

TypeScript#

Important:#

If certain parameters are incorrect, the import request may appear to start successfully but will never finish.

Incorrect Deployment Credentials:#

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.

Exception Handling#

There are three types of exceptions that may occur during import:
1.
Incorrect URL
GET /be/v1/tasks shows the failed Download Tar Task (dltar).
GET /be/v1/tasks/{taskId} reveals:
httpStatus: HTTP error code indicating failure.
exitCode: Error code providing further details (e.g., unreachable source).
2.
Incorrect sizeBytes Value
GET /be/v1/tasks shows the failed Download Tar Task (dltar).
GET /be/v1/tasks/{taskId} reveals:
sizeBytesActual: The actual file size.
sizeBytesExpected: The expected file size (provided in the request).
3.
Invalid Tarball
GET /be/v1/tasks shows the failed Make Raw Task.
GET /be/v1/tasks/{taskId} reveals:
fileReadFailed:
filename: Name of the file that failed to be read.
typeExpected: Expected file type.
typeDetected: Actual detected file type.

Acknowledging Warnings (Optional)#

These exceptions can be ignored, but if you want to acknowledge them:
Use PATCH /be/v1/tasks to mark them as acknowledged.

Required Permissions#

apps.update
See Roles for more details.

Request

Header Params

Body Params application/json

Example
{
    "appName": "{{appName}}",
    "url": "{{appNativeBuildURL}}",
    "sizeBytes": 555
}

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/builds' \
--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 '{
    "appName": "sushi",
    "url": "https://rockitplay-demo.akamaized.net/engine-fixtures/sushi/native-build.tar?token=exp=2041235666~acl=/engine-fixtures/sushi/*~hmac=df869da8c71a05f6a77ee7ed5a5902abd76e22734953d976973d6748d14beaf4",
    "sizeBytes": 555
}'

Responses

🟢200success
application/json
Body

Examples
{
    "status": "success",
    "message": "import request created"
}
🟢200no user url
🟠400missing-param
🟠401Unauthorized
🟠409409: busy
Modified at 2025-05-08 12:00:04
Previous
Creating Apps
Next
App Details
Built with