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 /stats?access_token=<access_token>

Return usage statistics.

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
items[].all integer the number of total workspace slots
items[].free integer the number of free workspace slots

Examples

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

Response example

{
    "workspace_slots": {
        "all": 200,
        "free": 185
    }
}

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
max: 30
page_token query boolean - 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[].project.config string configuration of the project in JSON format
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 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 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 terminated
items[].last_usage string date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD]
note that server time is used
items[].inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]; max 60
items[].workspace_token string workspace token for JS SDK integration
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 workspace streams
items[].streams.workspace_init_output object workspace init output info
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 workspace init error info
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 user can enter/resume the workspace
items[].permissions.remove boolean indicates whether user can remove the workspace
items[].permissions.stop boolean indicates whether user can stop the workspace
items[].max_inactivity_storage_time integer maximum time of workspace inactivity after which the workspace will be stopped [minutes]; max 43 200 (30 days)
items[].max_storage_time integer maximum time of workspace existence after which the workspace will be removed [minutes]; max 43 200 (30 days)
items[].workspace_url string url to the workspace IDE
pagination object pagination
pagination.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
pagination.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",
                "config": "{content of the configuration}"
            },
            "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": "token",
            "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"
                }
            },
            "state": {
                "code": 4,
                "name": "removed"
            },
            "workspace_url": "https://<endpoint>/workspace/93086f6043984e63b696c710317ee6eb"
        },
        {
            "id": "dec2d11d17054f0c84ab38415221bdb8",
            "project": {
                "id": "eef024c1d14f46319517a65edafb5ee3",
                "name": "EXAMPLE",
                "config": "{content of the configuration}"
            },
            "created_at": "2021-01-01 10:16:50 +0000",
            "terminated_at": null,
            "last_usage": "2021-01-01 10:40:07 +0000",
            "inactivity_timeout": 15,
            "workspace_token": "token",
            "workspace_token_required": true,
            "workspace_init_failed": false,
            "streams": {
                "workspace_init_output": null,
                "workspace_init_error": null
            },
            "state": {
                "code": 2,
                "name": "running"
            },
            "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 [minutes]; max 60
workspace_token_required form boolean - indicates whether workspace_token is required to open the workspace
workspace_init form string - override workspace initialization script
max_inactive_storage_time form integer 0 maximum time of workspace inactivity after which the workspace will be stopped [minutes]; max 43,200 (30 days)
max_storage_time form integer 0 maximum time of workspace existence after which the workspace will be removed [minutes]; max 43,200 (30 days)
files form file - tar.gz archive with files to extract to the workspace directory

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.project.config string configuration of the project in JSON format
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 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 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 terminated
workspace.last_usage string date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD]
note that server time is used
workspace.inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]; max 60
workspace.workspace_token string workspace token for JS SDK integration
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 workspace streams
workspace.streams.workspace_init_output object workspace init output info
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 workspace init error info
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 user can enter/resume the workspace
workspace.permissions.remove boolean indicates whether user can remove the workspace
workspace.permissions.stop boolean indicates whether user can stop the workspace
workspace.max_inactivity_storage_time integer maximum time of workspace inactivity after which the workspace will be stopped [minutes]; max 43 200 (30 days)
workspace.max_storage_time integer maximum time of workspace existence after which the workspace will be removed [minutes]; max 43 200 (30 days)
workspace.workspace_url string url to the workspace IDE

Examples

curl -X POST --form "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",
            "config": "{content of the configuration}"
        },
        "created_at": "2021-01-01 10:20:37 +0000",
        "terminated_at": null,
        "last_usage": null,
        "inactivity_timeout": 15,
        "workspace_token": "token",
        "workspace_token_required": true,
        "workspace_init_failed": false,
        "streams": {
            "workspace_init_output": null,
            "workspace_init_error": null
        },
        "state": {
            "code": 1,
            "name": "starting"
        },
        "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
project.config string configuration of the project in JSON format
state object workspace state
state.code string workspace state code
see section: workspace state
state.name string workspace state name
state.error_reason string 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 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 terminated
last_usage string date and time the workspace was last used [yyyy-mm-dd hh:mm:ss TZD]
note that server time is used
inactivity_timeout integer inactivity timeout after which the workspace will be terminated [minutes]; max 60
workspace_token string workspace token for JS SDK integration
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 workspace streams
streams.workspace_init_output object workspace init output info
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 workspace init error info
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 user can enter/resume the workspace
permissions.remove boolean indicates whether user can remove the workspace
permissions.stop boolean indicates whether user can stop the workspace
max_inactivity_storage_time integer maximum time of workspace inactivity after which the workspace will be stopped [minutes]; max 43 200 (30 days)
max_storage_time integer maximum time of workspace existence after which the workspace will be removed [minutes]; max 43 200 (30 days)
workspace_url string url to the workspace IDE

Examples

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

Response example

{
    "id": "93086f6043984e63b696c710317ee6eb",
    "project": {
        "id": "eef024c1d14f46319517a65edafb5ee3",
        "name": "EXAMPLE",
        "config": "{content of the configuration}"
    },
    "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": "token",
    "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
    },
    "max_inactive_storage_time": 0,
    "max_storage_time": 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
example: aW1hZ2UvY29tcG9uZW50cy9leGFtcGxlLm1pbg==

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
413 1111 file size limit exceeded. Max file size is 16MiB.

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
401 1 unauthorized access
404 1001 workspace not found

Success Response

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

Examples

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

Response example

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

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
401 1 unauthorized access
404 1001 workspace not found

Success Response

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

Examples

curl -X PUT 'https://<endpoint>/api/v1/workspaces/<workspace_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 Default value Description
access_token * query string - access token
ids * query string - comma separated list of submission identifiers
maximum number of identifiers: 20
limit query integer 10 limit of submissions to get; max: 20
page_token query boolean - 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 205104 identifiers are not provided
400 205105 invalid format of identifiers
400 205106 maximum number of identifiers exceeded
400 10 invalid request data

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 of submission creation [yyyy-mm-dd hh:mm:ss TZD]
note that server time is used
items[].project object programming project
items[].project.id string project id
items[].project.name string project name
items[].project.config string configuration of the project in JSON format
items[].result object submission result
items[].result.time float execution time [seconds]
items[].result.memory integer or null memory consumed by the program [kilobytes]
items[].result.signal integer or null signal raised by the program
items[].result.score float or null obtained score
items[].streams object submission streams
items[].streams.source object source code
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 aux data info
see section: keeping custom files after execution
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 final tests report
see section: technical reference for final tests report
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 debug log for Content Manager
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 stage init output info
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 stage init error info
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 stage build output info
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 stage build error info
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 stage run output info
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 stage run error info
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 stage test output info
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 stage test error info
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 stage post output info
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 stage post error info
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 workspace initialization script output info
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 workspace initialization script error info
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 submission stages
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
items[].stages.init.signal integer or null termination interrupt signal for stage
items[].stages.init.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
items[].stages.build.signal integer or null termination interrupt signal for stage
items[].stages.build.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
items[].stages.run.signal integer or null termination interrupt signal for stage
items[].stages.run.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
items[].stages.test.signal integer or null termination interrupt signal for stage
items[].stages.test.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
items[].stages.post.signal integer or null termination interrupt signal for stage
items[].stages.post.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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"
            },
            "result": {
                "status": {
                    "code": 15,
                    "name": "ok"
                },
                "score": 0,
                "time": 4.2,
                "memory": 239421,
                "signal": 0
            },
            "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": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_error"
                },
                "stage_build_output": {
                    "size": 80,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
                },
                "stage_build_error": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_error"
                },
                "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": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_error"
                },
                "stage_post_output": {
                    "size": 97,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
                },
                "stage_post_error": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_error"
                },
                "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,
                "memory": 553353,
                "signal": 0
            },
            "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": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_error"
                },
                "stage_build_output": {
                    "size": 80,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
                },
                "stage_build_error": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_error"
                },
                "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": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_error"
                },
                "stage_post_output": {
                    "size": 97,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
                },
                "stage_post_error": {
                    "size": 0,
                    "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_error"
                },
                "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 --form "project_id=ef66185208" --form "scenario=run" --form "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 of submission creation [yyyy-mm-dd hh:mm:ss TZD]
note that server time is used
project object programming project
project.id string project id
project.name string project name
project.config string configuration of the project in JSON format
result object submission result
result.time float execution time [seconds]
result.memory integer or null memory consumed by the program [kilobytes]
result.signal integer or null signal raised by the program
result.score float or null obtained score
streams object submission streams
streams.source object source code
streams.source.size integer source code length [bytes]
streams.source.uri string link to the file with source code
streams.auxdata object aux data info
see section: keeping custom files after execution
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 final tests report
see section: technical reference for final tests report
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 debug log for Content Manager
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 stage init output info
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 stage init error info
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 stage build output info
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 stage build error info
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 stage run output info
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 stage run error info
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 stage test output info
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 stage test error info
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 stage post output info
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 stage post error info
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 workspace initialization script output info
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 workspace initialization script error info
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 submission stages
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
stages.init.signal integer or null termination interrupt signal for stage
stages.init.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
stages.build.signal integer or null termination interrupt signal for stage
stages.build.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
stages.run.signal integer or null termination interrupt signal for stage
stages.run.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
stages.test.signal integer or null termination interrupt signal for stage
stages.test.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed
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
stages.post.signal integer or null termination interrupt signal for stage
stages.post.status_changed_to object or null details of the change in submission status for a particular stage
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 the status was changed

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"
    },
    "result": {
        "status": {
            "code": 13,
            "name": "time limit exceeded"
        },
        "score": 0,
        "time": 4.2,
        "memory": 239421,
        "signal": 0
    },
    "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": {
            "size": 0,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_init_error"
        },
        "stage_build_output": {
            "size": 80,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_output"
        },
        "stage_build_error": {
            "size": 0,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_build_error"
        },
        "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": {
            "size": 0,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_test_error"
        },
        "stage_post_output": {
            "size": 97,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_output"
        },
        "stage_post_error": {
            "size": 0,
            "uri": "https://<endpoint>/api/v1/submissions/1/stage_post_error"
        },
        "workspace_init_output": {
            "size": 45,
            "uri": "https://<endpoint>/api/v1/submissions/1/workspace_init_output"
        },
        "workspace_init_error": {
            "size": 0,
            "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": {
                "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; max: 20
page_token query boolean - 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 Configuration settings for the project.
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.
pagination object pagination
pagination.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
pagination.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.

Response example

{
    "items": [
        {
            "id": "8f69b531dceb41e7aa0dfd02fb131076",
            "name": "Base Project",
            "created_at": "2021-01-01 10:27:44 +0000",
            "config": "{content of the configuration}",
            "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": "{content of the configuration}",
            "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 Configuration settings for the project.
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.

Response example

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