Containers
API - Version 1.1

This is a technical reference for Sphere Engine Containers API Version 1.1.

Here you can find complete coverage of the API methods, including:

  • parameters with the type, validation rules, and description,
  • interpretation of response and error codes,
  • usage examples.

API Methods

GET /test?access_token=<access_token>

Testing Containers API. Every successful usage returns identical response.

Request parameters

Name Located in Type Description
access_token * query string access token

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access

Success Response

Field Type Description
message string message that states that it's possible to use API

Examples

curl -X GET 'https://<endpoint>/api/v1/test?access_token=<access_token>'

Response example

{
  "message": "You can use Sphere Engine Containers API"
}

GET /workspaces?access_token=<access_token>

Returns the list of workspaces of the quantity given by limit parameter.

Request parameters

Name Located in Type Default value Description
access_token * query string - access token
project_id query string - filter by project id
states query array - filter by states
example: states[]=1&states[]=2
see section: workspace state
limit query integer 10 limit of workspaces to get;
min: 1, max: 30
page_token query string - a token identifying a page of results to return;
this should be a page token returned from a previous call;
if empty, the first page of results is returned

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
400 10 invalid request data

Success Response

Field Type Description
items[].id string workspace id
items[].project object programming project
items[].project.id string project id
items[].project.name string project name
items[].state object workspace state
items[].state.code string workspace state code
see section: workspace state
items[].state.name string workspace state name
items[].state.error_reason string or null error reason
null if workspace is not in error state
items[].created_at string date and time of the workspace creation [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used
items[].terminated_at string or null date and time of the workspace termination [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace is not removed
items[].last_usage string or null date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace has never been used
items[].inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]
items[].workspace_token string workspace token for JS SDK integration (empty string if `workspace_token_required` is set to false)
items[].workspace_token_required boolean indicates whether `workspace_token` is required to open the workspace
items[].workspace_init_failed boolean indicates whether workspace initialization script has failed
items[].streams object details of the streams
items[].streams.workspace_init_output object or null workspace init output info;
null if the stream is not available
items[].streams.workspace_init_output.size integer size of the workspace initialization script output [bytes]
items[].streams.workspace_init_output.uri string link to the file with the workspace initialization output
items[].streams.workspace_init_error object or null workspace init error info;
null if the stream is not available
items[].streams.workspace_init_error.size integer size of the workspace initialization script error [bytes]
items[].streams.workspace_init_error.uri string link to the file with the workspace initialization error
items[].permissions object workspace permissions
items[].permissions.enter boolean indicates whether it is possible to enter the workspace
items[].permissions.remove boolean indicates whether the workspace can be removed
items[].permissions.stop boolean indicates whether the workspace can be stopped
items[].auto_resume boolean indicates whether the user can resume the workspace by entering it once it has been stopped;
if set to false, the workspace can only be resumed through an API call
items[].retention_time_stopped integer retention time of the stopped container, allowing for resuming [minutes]; 0 - cannot be resumed
(read more)
items[].retention_time_total integer maximum time after which the workspace will be unconditionally removed [minutes]; min 0 (disabled), max 43,200 (30 days)
(read more)
items[].config string configuration of the workspace in JSON format
(read more)
items[].workspace_url string url to the workspace IDE
items[].max_inactive_storage_time integer [deprecated] this parameter has been replaced with `retention_time_stopped`
items[].max_storage_time integer [deprecated] this parameter has been replaced with `retention_time_total`
paging object pagination
paging.previous_page_token string or null a token to retrieve the previous page of results; this field is null if there are no more results to retrieve
paging.next_page_token string or null a token to retrieve the next page of results; this field is null if there are no more results to retrieve

Examples

curl -X GET 'https://<endpoint>/api/v1/workspaces?project_id=<id>&access_token=<access_token>'

Response example

{
  "items": [
    {
      "id": "93086f6043984e63b696c710317ee6eb",
      "project": {
        "id": "eef024c1d14f46319517a65edafb5ee3",
        "name": "EXAMPLE"
      },
      "created_at": "2021-01-01 10:27:44 +0000",
      "terminated_at": "2021-01-01 10:44:08 +0000",
      "last_usage": "2021-01-01 10:28:51 +0000",
      "inactivity_timeout": 15,
      "state": {
        "code": 4,
        "name": "removed",
        "error_reason": null
      },
      "workspace_token": "1a1ccad4-26c9-4de7-bd3c-4d14f8056df1",
      "workspace_token_required": true,
      "workspace_init_failed": false,
      "streams": {
        "workspace_init_output": {
          "size": 123,
          "uri": "https://<endpoint>/api/v1/workspaces/93086f6043984e63b696c710317ee6eb/workspace_init_output"
        },
        "workspace_init_error": {
          "size": 45,
          "uri": "https://<endpoint>/api/v1/workspaces/93086f6043984e63b696c710317ee6eb/workspace_init_error"
        }
      },
      "config": "{content of the configuration}",
      "workspace_url": "https://<endpoint>/workspace/93086f6043984e63b696c710317ee6eb"
    },
    {
      "id": "dec2d11d17054f0c84ab38415221bdb8",
      "project": {
        "id": "eef024c1d14f46319517a65edafb5ee3",
        "name": "EXAMPLE"
      },
      "created_at": "2021-01-01 10:16:50 +0000",
      "terminated_at": null,
      "last_usage": "2021-01-01 10:40:07 +0000",
      "inactivity_timeout": 15,
      "state": {
        "code": 2,
        "name": "running",
        "error_reason": null
      },
      "workspace_token": "d174a8cc-733b-494b-a065-34c548720780",
      "workspace_token_required": true,
      "workspace_init_failed": false,
      "streams": {
        "workspace_init_output": null,
        "workspace_init_error": null
      },
      "auto_resume": true,
      "retention_time_stopped": 0,
      "retention_time_total": 0,
      "permissions": {
        "enter": true,
        "remove": true,
        "stop": false
      },
      "config": "{content of the configuration}",
      "workspace_url": "https://<endpoint>/workspace/dec2d11d17054f0c84ab38415221bdb8"
    }
  ],
  "paging": {
    "previous_page_token": null,
    "next_page_token": "MTA="
  }
}

POST /workspaces?access_token=<access_token>

Create a new workspace.

Request parameters

Name Located in Type Default value Description
access_token * query string - access token
project_id * form string - project id
project_config form string - project config to override; use the encoded JSON format
inactivity_timeout form integer 15 inactivity timeout after workspace will be terminated or stopped [minutes]; min 10, max 60
workspace_token_required form boolean false indicates whether workspace token is required to open the workspace (read more)
workspace_init form string - override workspace initialization script
auto_resume form boolean true indicates whether the user can resume the workspace by entering it once it has been stopped;
if set to false, the workspace can only be resumed through an API call
retention_time_stopped form integer 0 retention time of the stopped container, allowing for resuming [minutes]; min 0 (cannot be resumed), max 43,200 (30 days)
(read more)
retention_time_total form integer 0 maximum time after which the workspace will be unconditionally removed [minutes]; min 0 (disabled), max 43,200 (30 days)
(read more)
files form file - tar.gz archive with files to extract to the workspace directory
max_inactive_storage_time form integer 0 [deprecated] this parameter has been replaced with `retention_time_stopped`
max_storage_time form integer 0 [deprecated] this parameter has been replaced with `retention_time_total`

Response HTTP Code

HTTP Code Error Code Description
201 - success
401 1 unauthorized access
400 10 invalid request data
400 1003 creation failed
409 200611 not enough free slots to create the workspace
409 200510 the project is temporarily unavailable
409 200612 another edit session is already active

Success Response

Field Type Description
message string message confirming that the workspace creation has been initialized
workspace object information about initialized workspace
workspace.id string workspace id
workspace.project object programming project
workspace.project.id string project id
workspace.project.name string project name
workspace.state object workspace state
workspace.state.code string workspace state code
see section: workspace state
workspace.state.name string workspace state name
workspace.state.error_reason string or null error reason
null if workspace is not in error state
workspace.created_at string date and time of the workspace creation [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used
workspace.terminated_at string or null date and time of the workspace termination [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace is not removed
workspace.last_usage string or null date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace has never been used
workspace.inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]
workspace.workspace_token string workspace token for JS SDK integration (empty string if `workspace_token_required` is set to false)
workspace.workspace_token_required boolean indicates whether `workspace_token` is required to open the workspace
workspace.workspace_init_failed boolean indicates whether workspace initialization script has failed
workspace.streams object details of the streams
workspace.streams.workspace_init_output object or null workspace init output info;
null if the stream is not available
workspace.streams.workspace_init_output.size integer size of the workspace initialization script output [bytes]
workspace.streams.workspace_init_output.uri string link to the file with the workspace initialization output
workspace.streams.workspace_init_error object or null workspace init error info;
null if the stream is not available
workspace.streams.workspace_init_error.size integer size of the workspace initialization script error [bytes]
workspace.streams.workspace_init_error.uri string link to the file with the workspace initialization error
workspace.permissions object workspace permissions
workspace.permissions.enter boolean indicates whether it is possible to enter the workspace
workspace.permissions.remove boolean indicates whether the workspace can be removed
workspace.permissions.stop boolean indicates whether the workspace can be stopped
workspace.auto_resume boolean indicates whether the user can resume the workspace by entering it once it has been stopped;
if set to false, the workspace can only be resumed through an API call
workspace.retention_time_stopped integer retention time of the stopped container, allowing for resuming [minutes]; 0 - cannot be resumed
(read more)
workspace.retention_time_total integer maximum time after which the workspace will be unconditionally removed [minutes]; min 0 (disabled), max 43,200 (30 days)
(read more)
workspace.config string configuration of the workspace in JSON format
(read more)
workspace.workspace_url string url to the workspace IDE
workspace.max_inactive_storage_time integer [deprecated] this parameter has been replaced with `retention_time_stopped`
workspace.max_storage_time integer [deprecated] this parameter has been replaced with `retention_time_total`

Examples

curl -X POST \
    -F "project_id=82da33ed1b7e" \
    "https://<endpoint>/api/v1/workspaces?access_token=<access_token>"

Response example

{
  "message": "Workspace has been created",
  "workspace": {
    "id": "48dba362e85e4aebac3dc8e6b0677ff7",
    "project": {
      "id": "eef024c1d14f46319517a65edafb5ee3",
      "name": "EXAMPLE"
    },
    "created_at": "2021-01-01 10:20:37 +0000",
    "terminated_at": null,
    "last_usage": null,
    "inactivity_timeout": 15,
    "workspace_token": "df654bd3-76d6-4a35-9793-5a2d6c0936d4",
    "workspace_token_required": true,
    "workspace_init_failed": false,
    "streams": {
      "workspace_init_output": null,
      "workspace_init_error": null
    },
    "state": {
      "code": 1,
      "name": "starting",
      "error_reason": null
    },
    "auto_resume": true,
    "retention_time_stopped": 0,
    "retention_time_total": 0,
    "permissions": {
      "enter": true,
      "remove": false,
      "stop": false
    },
    "config": "{content of the configuration}",
    "workspace_url": "https://<endpoint>/workspace/48dba362e85e4aebac3dc8e6b0677ff7"
  }
}

GET /workspaces/:id?access_token=<access_token>

Retrieve information about a workspace.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string workspace id

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
404 1001 workspace not found

Success Response

Field Type Description
id string workspace id
project object programming project
project.id string project id
project.name string project name
state object workspace state
state.code string workspace state code
see section: workspace state
state.name string workspace state name
state.error_reason string or null error reason
null if workspace is not in error state
created_at string date and time of the workspace creation [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used
terminated_at string or null date and time of the workspace termination [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace is not removed
last_usage string or null date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used;
null if workspace has never been used
inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]
workspace_token string workspace token for JS SDK integration (empty string if `workspace_token_required` is set to false)
workspace_token_required boolean indicates whether `workspace_token` is required to open the workspace
workspace_init_failed boolean indicates whether workspace initialization script has failed
streams object details of the streams
streams.workspace_init_output object or null workspace init output info;
null if the stream is not available
streams.workspace_init_output.size integer size of the workspace initialization script output [bytes]
streams.workspace_init_output.uri string link to the file with the workspace initialization output
streams.workspace_init_error object or null workspace init error info;
null if the stream is not available
streams.workspace_init_error.size integer size of the workspace initialization script error [bytes]
streams.workspace_init_error.uri string link to the file with the workspace initialization error
permissions object workspace permissions
permissions.enter boolean indicates whether it is possible to enter the workspace
permissions.remove boolean indicates whether the workspace can be removed
permissions.stop boolean indicates whether the workspace can be stopped
auto_resume boolean indicates whether the user can resume the workspace by entering it once it has been stopped;
if set to false, the workspace can only be resumed through an API call
retention_time_stopped integer retention time of the stopped container, allowing for resuming [minutes]; 0 - cannot be resumed
(read more)
retention_time_total integer maximum time after which the workspace will be unconditionally removed [minutes]; min 0 (disabled), max 43,200 (30 days)
(read more)
config string configuration of the workspace in JSON format
(read more)
workspace_url string url to the workspace IDE
max_inactive_storage_time integer [deprecated] this parameter has been replaced with `retention_time_stopped`
max_storage_time integer [deprecated] this parameter has been replaced with `retention_time_total`

Examples

curl -X GET 'https://<endpoint>/api/v1/workspaces/<id>?access_token=<access_token>'

Response example

{
  "id": "93086f6043984e63b696c710317ee6eb",
  "project": {
    "id": "eef024c1d14f46319517a65edafb5ee3",
    "name": "EXAMPLE"
  },
  "created_at": "2021-01-01 10:27:44 +0000",
  "terminated_at": "2021-01-01 10:44:08 +0000",
  "last_usage": "2021-01-01 10:28:51 +0000",
  "inactivity_timeout": 15,
  "workspace_token": "283994f5-7c4a-44c7-9781-6720243def0e",
  "workspace_token_required": true,
  "workspace_init_failed": false,
  "streams": {
    "workspace_init_output": {
      "size": 123,
      "uri": "https://<endpoint>/api/v1/workspaces/93086f6043984e63b696c710317ee6eb/workspace_init_output"
    },
    "workspace_init_error": {
      "size": 67,
      "uri": "https://<endpoint>/api/v1/workspaces/93086f6043984e63b696c710317ee6eb/workspace_init_error"
    }
  },
  "state": {
    "code": 4,
    "name": "removed",
    "error_reason": null
  },
  "auto_resume": true,
  "config": "{content of the configuration}",
  "retention_time_stopped": 0,
  "retention_time_total": 0,
  "permissions": {
    "enter": false,
    "remove": false,
    "stop": false
  },
  "workspace_url": "https://<endpoint>/workspace/93086f6043984e63b696c710317ee6eb"
}

GET /workspaces/:id/files/:path?access_token=<access_token>

Retrieve file from a running workspace.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string workspace id
path * path string path to file encoded in base64
e.g. docs/TEST.md | ZG9jcy9URVNULm1k
TEST.md | VEVTVC5tZA==

Response HTTP Code

HTTP Code Error Code Description
200 - success
400 1105 failed to decode the file path from UTF-8 format
400 1105 failed to decode the file path from Base64
400 1101 file not found
400 1101 provided path is not a file
400 1102 permission denied to read the file
401 1 unauthorized access
404 1001 workspace not found
404 1108 workspace not available
404 1108 workspace is stopped
413 1111 file size limit exceeded (max file size is 16MiB)
500 1103 unable to read file

Examples

$ curl -X PUT "https://<endpoint>/api/v1/workspaces/<id>/files/<path>?access_token=<access_token>"

// for example for the file `docs/TEST.md`
// use encoded `ZG9jcy9URVNULm1k`
$ curl -X PUT "https://<endpoint>/api/v1/workspaces/<id>/files/ZG9jcy9URVNULm1k?access_token=<access_token>"

Response example

Raw binary data of the file.

PUT /workspaces/:id/stop?access_token=<access_token>

Stop a workspace.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string workspace id

Response HTTP Code

HTTP Code Error Code Description
200 - success
400 1013 the workspace cannot be stopped
401 1 unauthorized access
404 1001 workspace not found
500 1003 stop the workspace failed

Success Response

Field Type Description
message string message confirming that the workspace has been stopped

Examples

curl -X PUT "https://<endpoint>/api/v1/workspaces/<id>/stop?access_token=<access_token>"

Response example

{
  "message": "Workspace has been stopped"
}

PUT /workspaces/:id/resume?access_token=<access_token>

Resume a stopped workspace.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string workspace id

Response HTTP Code

HTTP Code Error Code Description
200 - success
400 1010 the workspace cannot be resumed due to an internal error
400 1013 the workspace is not stopped
401 1 unauthorized access
404 1001 workspace not found
409 200611 not enough free slots to resume the workspace
500 1008 the workspace cannot be resumed due to an internal error
500 1013 the workspace cannot be resumed due to an internal error
500 1003 the workspace cannot be resumed due to an internal error

Success Response

Field Type Description
message string message confirming that the workspace will be resumed

Examples

curl -X PUT "https://<endpoint>/api/v1/workspaces/<id>/resume?access_token=<access_token>"

Response example

{
  "message": "Workspace is resuming"
}

PUT /workspaces/:id/remove?access_token=<access_token>

Remove a workspace.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string workspace id

Response HTTP Code

HTTP Code Error Code Description
200 - success
400 1013 the workspace cannot be removed
401 1 unauthorized access
404 1001 workspace not found
500 1003 remove the workspace failed

Success Response

Field Type Description
message string message confirming that the workspace has been removed

Examples

curl -X PUT "https://<endpoint>/api/v1/workspaces/<id>/remove?access_token=<access_token>"

Response example

{
  "message": "Workspace has been removed"
}

GET /submissions?access_token=<access_token>

Retrieve information about submissions.

Request parameters

Name Located in Type Description
access_token * query string access token
ids * query string comma separated list of submission identifiers
maximum number of identifiers: 20

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
400 205104 identifiers are not provided
400 205105 invalid format of identifiers
400 205106 maximum number of identifiers exceeded

Success Response

Field Type Description
items[].id integer submission id
items[].executing boolean indicates whether submission is being executed
items[].date string date and time at which the scenario execution began [yyyy-mm-dd hh:mm:ss TZD] always in UTC timezone
items[].project object programming project
items[].project.id string project id
items[].project.name string project name
items[].scenario string executed scenario
items[].result object submission result
items[].result.status object submission status
items[].result.status.code integer result status code (see section: submission status)
items[].result.status.name string status name
items[].result.time float or null execution time [seconds];
null if submission is executing
items[].result.score float or null score;
null if submission is executing
items[].streams object details of the streams
items[].streams.source object or null source code;
null if the stream is not available
items[].streams.source.size integer source code length [bytes]
items[].streams.source.uri string link to the file with source code
items[].streams.auxdata object or null auxdata stream details;
null if the stream is not available;
the stream content is generated from directories defined in the scenario configuration; for more information about auxdata, see Extracting custom files from a workspace
items[].streams.auxdata.size integer size of auxiliary data stream [bytes]
items[].streams.auxdata.uri string link to the file with auxiliary data generated by the submission
items[].streams.tests_report object or null details of the tests report stream;
null if the stream is not available;
for more information, see Tests report format
items[].streams.tests_report.size integer size of final tests report [bytes]
items[].streams.tests_report.uri string link to the file with final tests report generated by the submission
items[].streams.debug_log object or null debug log for Content Manager;
null if the stream is not available
items[].streams.debug_log.size integer size of debug log data [bytes]
items[].streams.debug_log.uri string link to the file with debug log generated by the submission
items[].streams.stage_init_output object or null stage init output info;
null if the stream is not available
items[].streams.stage_init_output.size integer size of the init stage's output [bytes]
items[].streams.stage_init_output.uri string link to the file with the init stage's output
items[].streams.stage_init_error object or null stage init error info;
null if the stream is not available
items[].streams.stage_init_error.size integer size of the init stage's error [bytes]
items[].streams.stage_init_error.uri string link to the file with the init stage's error
items[].streams.stage_build_output object or null stage build output info;
null if the stream is not available
items[].streams.stage_build_output.size integer size of the build stage's output [bytes]
items[].streams.stage_build_output.uri string link to the file with the build stage's output
items[].streams.stage_build_error object or null stage build error info;
null if the stream is not available
items[].streams.stage_build_error.size integer size of the build stage's error [bytes]
items[].streams.stage_build_error.uri string link to the file with the build stage's error
items[].streams.stage_run_output object or null stage run output info;
null if the stream is not available
items[].streams.stage_run_output.size integer size of the run stage's output [bytes]
items[].streams.stage_run_output.uri string link to the file with the run stage's output
items[].streams.stage_run_error object or null stage run error info;
null if the stream is not available
items[].streams.stage_run_error.size integer size of the run stage's error [bytes]
items[].streams.stage_run_error.uri string link to the file with the run stage's error
items[].streams.stage_test_output object or null stage test output info;
null if the stream is not available
items[].streams.stage_test_output.size integer size of the test stage's output [bytes]
items[].streams.stage_test_output.uri string link to the file with the test stage's output
items[].streams.stage_test_error object or null stage test error info;
null if the stream is not available
items[].streams.stage_test_error.size integer size of the test stage's error [bytes]
items[].streams.stage_test_error.uri string link to the file with the test stage's error
items[].streams.stage_post_output object or null stage post output info;
null if the stream is not available
items[].streams.stage_post_output.size integer size of the post stage's output [bytes]
items[].streams.stage_post_output.uri string link to the file with the post stage's output
items[].streams.stage_post_error object or null stage post error info;
null if the stream is not available
items[].streams.stage_post_error.size integer size of the post stage's error [bytes]
items[].streams.stage_post_error.uri string link to the file with the post stage's error
items[].streams.workspace_init_output object or null workspace initialization script output info;
null if the stream is not available
items[].streams.workspace_init_output.size integer size of the workspace initialization script output [bytes]
items[].streams.workspace_init_output.uri string link to the file with the workspace initialization output
items[].streams.workspace_init_error object or null workspace initialization script error info;
null if the stream is not available
items[].streams.workspace_init_error.size integer size of the workspace initialization script error [bytes]
items[].streams.workspace_init_error.uri string link to the file with the workspace initialization error
items[].stages object or null details of the stages;
null if submission is executing or stage results are not available
items[].stages.init object initialization stage
items[].stages.init.time float stage execution time [seconds]
items[].stages.init.skipped boolean whether the stage has been skipped
items[].stages.init.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
items[].stages.init.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
items[].stages.init.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
items[].stages.init.status_changed_to.code integer status code (see section: submission status)
items[].stages.init.status_changed_to.name string status name
items[].stages.init.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
items[].stages.build object build stage
items[].stages.build.time float stage execution time [seconds]
items[].stages.build.skipped boolean whether the stage has been skipped
items[].stages.build.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
items[].stages.build.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
items[].stages.build.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
items[].stages.build.status_changed_to.code integer status code (see section: submission status)
items[].stages.build.status_changed_to.name string status name
items[].stages.build.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
items[].stages.run object execution stage
items[].stages.run.time float stage execution time [seconds]
items[].stages.run.skipped boolean whether the stage has been skipped
items[].stages.run.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
items[].stages.run.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
items[].stages.run.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
items[].stages.run.status_changed_to.code integer status code (see section: submission status)
items[].stages.run.status_changed_to.name string status name
items[].stages.run.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
items[].stages.test object evaluation stage
items[].stages.test.time float stage execution time [seconds]
items[].stages.test.skipped boolean whether the stage has been skipped
items[].stages.test.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
items[].stages.test.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
items[].stages.test.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
items[].stages.test.status_changed_to.code integer status code (see section: submission status)
items[].stages.test.status_changed_to.name string status name
items[].stages.test.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
items[].stages.post object finalization stage
items[].stages.post.time float stage execution time [seconds]
items[].stages.post.skipped boolean whether the stage has been skipped
items[].stages.post.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
items[].stages.post.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
items[].stages.post.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
items[].stages.post.status_changed_to.code integer status code (see section: submission status)
items[].stages.post.status_changed_to.name string status name
items[].stages.post.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
items[].uri string link to submission details

Examples

curl -X GET 'https://<endpoint>/api/v1/submissions?ids=<ids>&access_token=<access_token>'

Response example

{
  "items": [
    {
      "id": 1,
      "executing": false,
      "date": "2021-01-01 14:21:57 +0000",
      "project": {
        "id": "ef66185208fd4cce9026c5f1a4486c72",
        "name": "EXAMPLE"
      },
      "scenario": "run",
      "result": {
        "status": {
          "code": 15,
          "name": "ok"
        },
        "score": 0,
        "time": 4.2
      },
      "streams": {
        "source": {
          "size": 88,
          "uri": "https://<endpoint>/api/v1/submissions/1/source"
        },
        "auxdata": {
          "size": 105,
          "uri": "https://<endpoint>/api/v1/submissions/1/auxdata"
        },
        "tests_report": {
          "size": 8774,
          "uri": "https://<endpoint>/api/v1/submissions/1/tests_report"
        },
        "debug_log": {
          "size": 142,
          "uri": "https://<endpoint>/api/v1/submissions/1/debug_log"
        },
        "stage_init_output": {
          "size": 97,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_output"
        },
        "stage_init_error": null,
        "stage_build_output": {
          "size": 80,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
        },
        "stage_build_error": null,
        "stage_run_output": {
          "size": 1134,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_output"
        },
        "stage_run_error": {
          "size": 567,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_error"
        },
        "stage_test_output": {
          "size": 900,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_output"
        },
        "stage_test_error": null,
        "stage_post_output": {
          "size": 97,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
        },
        "stage_post_error": null,
        "workspace_init_output": {
          "size": 655,
          "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_output"
        },
        "workspace_init_error": {
          "size": 451,
          "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_error"
        }
      },
      "stages": {
        "init": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "build": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "run": {
          "time": 4.2,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "test": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "post": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        }
      },
      "uri": "https://<endpoint>/api/v1/submissions/1"
    },
    {
      "id": 42,
      "executing": false,
      "date": "2021-02-04 04:27:14 +0000",
      "project": {
        "id": "ef66185208fd4cce9026c5f1a4486c72",
        "name": "EXAMPLE"
      },
      "result": {
        "status": {
          "code": 13,
          "name": "time limit exceeded"
        },
        "score": 0,
        "time": 7.45
      },
      "streams": {
        "source": {
          "size": 88,
          "uri": "https://<endpoint>/api/v1/submissions/1/source"
        },
        "auxdata": {
          "size": 105,
          "uri": "https://<endpoint>/api/v1/submissions/1/auxdata"
        },
        "tests_report": {
          "size": 8774,
          "uri": "https://<endpoint>/api/v1/submissions/1/tests_report"
        },
        "debug_log": {
          "size": 142,
          "uri": "https://<endpoint>/api/v1/submissions/1/debug_log"
        },
        "stage_init_output": {
          "size": 97,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_output"
        },
        "stage_init_error": null,
        "stage_build_output": {
          "size": 80,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
        },
        "stage_build_error": null,
        "stage_run_output": {
          "size": 1134,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_output"
        },
        "stage_run_error": {
          "size": 567,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_error"
        },
        "stage_test_output": {
          "size": 900,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_output"
        },
        "stage_test_error": null,
        "stage_post_output": {
          "size": 97,
          "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
        },
        "stage_post_error": null,
        "workspace_init_output": {
          "size": 132,
          "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_output"
        },
        "workspace_init_error": {
          "size": 34,
          "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_error"
        }
      },
      "stages": {
        "init": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "build": {
          "time": 0,
          "skipped": false,
          "signal": null,
          "status_changed_to": null
        },
        "run": {
          "time": 7.45,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": {
            "code": 13,
            "name": "time limit exceeded",
            "desc": null
          }
        },
        "test": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        },
        "post": {
          "time": 0,
          "skipped": false,
          "exit_code": 0,
          "signal": null,
          "status_changed_to": null
        }
      },
      "uri": "https://<endpoint>/api/v1/submissions/42"
    }
  ]
}

POST /submissions?access_token=<access_token>

Create a new submission.

Request parameters

Name Located in Type Description
access_token * query string access token
project_id * form string project id
source * form file tar.gz archive
scenario * form string project scenario to be executed
project_config form string project config to override; use the encoded JSON format
workspace_init form string override workspace initialization script

Response HTTP Code

HTTP Code Error Code Description
201 - success
401 1 unauthorized access
400 10 invalid request data
400 1003 creation failed

Success Response

Field Type Description
message string message confirming that the workspace creation has been initialized
id integer id of created submission

Examples

curl -X POST \
    -F "project_id=ef66185208" \
    -F "source=@source.tar.gz" \
    "https://<endpoint>/api/v1/submissions?access_token=<access_token>"

Response example

{
  "message": "Submission has been created",
  "id": 42
}

GET /submissions/:id?access_token=<access_token>

Retrieve information about a submission.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path integer submission id

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
404 1001 submission not found

Success Response

Field Type Description
id integer submission id
executing boolean indicates whether submission is being executed
date string date and time at which the scenario execution began [yyyy-mm-dd hh:mm:ss TZD] always in UTC timezone
project object programming project
project.id string project id
project.name string project name
scenario string executed scenario
result object submission result
result.status object submission status
result.status.code integer result status code (see section: submission status)
result.status.name string status name
result.time float or null execution time [seconds];
null if submission is executing
result.score float or null score;
null if submission is executing
streams object details of the streams
streams.source object or null source code;
null if the stream is not available
streams.source.size integer source code length [bytes]
streams.source.uri string link to the file with source code
streams.auxdata object or null auxdata stream details;
null if the stream is not available;
the stream content is generated from directories defined in the scenario configuration; for more information about auxdata, see Extracting custom files from a workspace
streams.auxdata.size integer size of auxiliary data stream [bytes]
streams.auxdata.uri string link to the file with auxiliary data generated by the submission
streams.tests_report object or null details of the tests report stream;
null if the stream is not available;
for more information, see Tests report format
streams.tests_report.size integer size of final tests report [bytes]
streams.tests_report.uri string link to the file with final tests report generated by the submission
streams.debug_log object or null debug log for Content Manager;
null if the stream is not available
streams.debug_log.size integer size of debug log data [bytes]
streams.debug_log.uri string link to the file with debug log generated by the submission
streams.stage_init_output object or null stage init output info;
null if the stream is not available
streams.stage_init_output.size integer size of the init stage's output [bytes]
streams.stage_init_output.uri string link to the file with the init stage's output
streams.stage_init_error object or null stage init error info;
null if the stream is not available
streams.stage_init_error.size integer size of the init stage's error [bytes]
streams.stage_init_error.uri string link to the file with the init stage's error
streams.stage_build_output object or null stage build output info;
null if the stream is not available
streams.stage_build_output.size integer size of the build stage's output [bytes]
streams.stage_build_output.uri string link to the file with the build stage's output
streams.stage_build_error object or null stage build error info;
null if the stream is not available
streams.stage_build_error.size integer size of the build stage's error [bytes]
streams.stage_build_error.uri string link to the file with the build stage's error
streams.stage_run_output object or null stage run output info;
null if the stream is not available
streams.stage_run_output.size integer size of the run stage's output [bytes]
streams.stage_run_output.uri string link to the file with the run stage's output
streams.stage_run_error object or null stage run error info;
null if the stream is not available
streams.stage_run_error.size integer size of the run stage's error [bytes]
streams.stage_run_error.uri string link to the file with the run stage's error
streams.stage_test_output object or null stage test output info;
null if the stream is not available
streams.stage_test_output.size integer size of the test stage's output [bytes]
streams.stage_test_output.uri string link to the file with the test stage's output
streams.stage_test_error object or null stage test error info;
null if the stream is not available
streams.stage_test_error.size integer size of the test stage's error [bytes]
streams.stage_test_error.uri string link to the file with the test stage's error
streams.stage_post_output object or null stage post output info;
null if the stream is not available
streams.stage_post_output.size integer size of the post stage's output [bytes]
streams.stage_post_output.uri string link to the file with the post stage's output
streams.stage_post_error object or null stage post error info;
null if the stream is not available
streams.stage_post_error.size integer size of the post stage's error [bytes]
streams.stage_post_error.uri string link to the file with the post stage's error
streams.workspace_init_output object or null workspace initialization script output info;
null if the stream is not available
streams.workspace_init_output.size integer size of the workspace initialization script output [bytes]
streams.workspace_init_output.uri string link to the file with the workspace initialization output
streams.workspace_init_error object or null workspace initialization script error info;
null if the stream is not available
streams.workspace_init_error.size integer size of the workspace initialization script error [bytes]
streams.workspace_init_error.uri string link to the file with the workspace initialization error
stages object or null details of the stages;
null if submission is executing or stage results are not available
stages.init object initialization stage
stages.init.time float stage execution time [seconds]
stages.init.skipped boolean whether the stage has been skipped
stages.init.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
stages.init.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
stages.init.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
stages.init.status_changed_to.code integer status code (see section: submission status)
stages.init.status_changed_to.name string status name
stages.init.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
stages.build object build stage
stages.build.time float stage execution time [seconds]
stages.build.skipped boolean whether the stage has been skipped
stages.build.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
stages.build.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
stages.build.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
stages.build.status_changed_to.code integer status code (see section: submission status)
stages.build.status_changed_to.name string status name
stages.build.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
stages.run object execution stage
stages.run.time float stage execution time [seconds]
stages.run.skipped boolean whether the stage has been skipped
stages.run.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
stages.run.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
stages.run.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
stages.run.status_changed_to.code integer status code (see section: submission status)
stages.run.status_changed_to.name string status name
stages.run.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
stages.test object evaluation stage
stages.test.time float stage execution time [seconds]
stages.test.skipped boolean whether the stage has been skipped
stages.test.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
stages.test.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
stages.test.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
stages.test.status_changed_to.code integer status code (see section: submission status)
stages.test.status_changed_to.name string status name
stages.test.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description
stages.post object finalization stage
stages.post.time float stage execution time [seconds]
stages.post.skipped boolean whether the stage has been skipped
stages.post.exit_code integer or null stage termination exit code;
null if exit code is not available (e.g. stage skipped)
stages.post.signal integer or null interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
stages.post.status_changed_to object or null details of the execution status change within the stage;
null if status hasn't changed
stages.post.status_changed_to.code integer status code (see section: submission status)
stages.post.status_changed_to.name string status name
stages.post.status_changed_to.desc string or null description of the reason for the status change;
null if there is no description

Examples

curl -X GET 'https://<endpoint>/api/v1/submissions/<id>?access_token=<access_token>'

Response example

{
  "id": 1,
  "executing": false,
  "date": "2021-01-01 14:21:57 +0000",
  "project": {
    "id": "ef66185208fd4cce9026c5f1a4486c72",
    "name": "EXAMPLE"
  },
  "scenario": "run",
  "result": {
    "status": {
      "code": 13,
      "name": "time limit exceeded"
    },
    "score": 0,
    "time": 4.2
  },
  "streams": {
    "source": {
      "size": 88,
      "uri": "https://<endpoint>/api/v1/submissions/1/source"
    },
    "auxdata": {
      "size": 105,
      "uri": "https://<endpoint>/api/v1/submissions/1/auxdata"
    },
    "tests_report": {
      "size": 8774,
      "uri": "https://<endpoint>/api/v1/submissions/1/tests_report"
    },
    "debug_log": {
      "size": 142,
      "uri": "https://<endpoint>/api/v1/submissions/1/debug_log"
    },
    "stage_init_output": {
      "size": 97,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_output"
    },
    "stage_init_error": null,
    "stage_build_output": {
      "size": 80,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
    },
    "stage_build_error": null,
    "stage_run_output": {
      "size": 1134,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_output"
    },
    "stage_run_error": {
      "size": 567,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_run_error"
    },
    "stage_test_output": {
      "size": 900,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_output"
    },
    "stage_test_error": null,
    "stage_post_output": {
      "size": 97,
      "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
    },
    "stage_post_error": null,
    "workspace_init_output": {
      "size": 45,
      "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_output"
    },
    "workspace_init_error": null
  },
  "stages": {
    "init": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "build": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "run": {
      "time": 4.2,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": {
        "code": 13,
        "name": "time limit exceeded",
        "desc": null
      }
    },
    "test": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    },
    "post": {
      "time": 0,
      "skipped": false,
      "exit_code": 0,
      "signal": null,
      "status_changed_to": null
    }
  }
}

GET /submissions/:id/:stream?access_token=<access_token>

Retrieve raw submission stream data.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path integer submission id
stream * path string stream name
enum: source, auxdata, tests_report, debug_log, stage_init_output, stage_init_error, stage_build_output, stage_build_error, stage_run_output, stage_run_error, stage_test_output, stage_test_error, stage_post_output, stage_post_error, workspace_init_output, workspace_init_error

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
404 1001 submission not found
404 1101 stream not found

Examples

curl -X GET 'https://<endpoint>/api/v1/submissions/<id>/output?access_token=<access_token>'

Response example

Raw data from selected stream.

GET /projects?access_token=<access_token>

Retrieve information about projects.

Request parameters

Name Located in Type Default value Description
access_token * query string - access token
limit query integer 10 limit of projects to get; min:1, max: 20
page_token query string - a token identifying a page of results to return;
this should be a page token returned from a previous call;
if empty, the first page of results is returned

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
400 10 invalid request data

Success Response

Field Type Description
items[].id string project id
items[].name string project name
items[].created_at string date and time of project creation [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used
items[].config object configs
items[].config.project_config string configuration of the project in JSON format
(read more)
items[].config.workspace_init string workspace initialization script
items[].stack string the technology stack used for the project
items[].template boolean indicates whether the project is a template
items[].description string project description
items[].slots integer number of slots used by the project
paging object pagination
paging.previous_page_token string or null a token to retrieve the previous page of results; this field is null if there are no more results to retrieve
paging.next_page_token string or null a token to retrieve the next page of results; this field is null if there are no more results to retrieve

Examples

curl -X GET 'https://<endpoint>/api/v1/projects?access_token=<access_token>'

Response example

{
  "items": [
    {
      "id": "8f69b531dceb41e7aa0dfd02fb131076",
      "name": "Base Project",
      "created_at": "2021-01-01 10:27:44 +0000",
      "config": {
        "project_config": "{content of the configuration}",
        "workspace_init": "{workspace initialization script}"
      },
      "stack": "",
      "template": true,
      "description": "Base template project, can be used as a starting point for new projects.",
      "slots": 10
    },
    {
      "id": "93086f6043984e63b696c710317ee6eb",
      "name": "Example",
      "created_at": "2021-01-02 11:32:44 +0000",
      "config": {
        "project_config": "{content of the configuration}",
        "workspace_init": "{workspace initialization script}"
      },
      "stack": "",
      "template": false,
      "description": "",
      "slots": 5
    }
  ],
  "paging": {
    "previous_page_token": null,
    "next_page_token": "MTA="
  }
}

GET /projects/:id?access_token=<access_token>

Retrieve information about a project.

Request parameters

Name Located in Type Description
access_token * query string access token
id * path string project id

Response HTTP Code

HTTP Code Error Code Description
200 - success
401 1 unauthorized access
404 200201 project not found

Success Response

Field Type Description
id string project id
name string project name
created_at string date and time of project creation [yyyy-mm-dd hh:mm:ss TZD];
note that server time is used
config object configs
config.project_config string configuration of the project in JSON format
(read more)
config.workspace_init string workspace initialization script
stack string the technology stack used for the project
template boolean indicates whether the project is a template
description string project description
slots integer number of slots used by the project

Examples

curl -X GET 'https://<endpoint>/api/v1/projects/<id>?access_token=<access_token>'

Response example

{
  "id": "93086f6043984e63b696c710317ee6eb",
  "name": "Base Project",
  "created_at": "2021-01-01 10:27:44 +0000",
  "config": {
    "project_config": "{content of the configuration}",
    "workspace_init": "{workspace initialization script}"
  },
  "stack": "",
  "template": true,
  "description": "Base template project, can be used as a starting point for new projects.",
  "slots": 10
}
  Contents