Capsule API

Prerequisites

• Token with capsule scope

• The capsule ID to pass to the API call

You can find the capsule's ID on the metadata page

Get capsule's metadata

GET https://{domain}codeocean.com/api/v1/capsules/{capsule_id}

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain
{capsule_id}*	String	Capsule's id

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

200: OK

{
    "cloned_from_url": (optional) - string - the repo that the capsule clone from,
    "created": int64 - capsule creation time,
    "description": (optional) - string - capsule description,
    "field": (optional) - string - the capsule research field,
    "id": string - the capsule ID,
    "keywords": (optional) - array of strings,
    "name": string - the capsule display name,
    "owner": string - the capsule owner’s ID,
    "published_capsule":  (optional) - string - published capsule ID,
    "slug": string - alternate capsule ID,
    "status": status of the capsule (non_published, submitted, publishing, published, verified)
}

Example of getting capsule's metadata:

Request Example

curl --location --request GET 'https://acmecorp.codeocean.com/api/v1/capsules/1d8288da-0785-4e4f-aa37-2d1db3636bc4' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your capsule's id.

Response Example

{
    "cloned_from_url":"",
    "created":1646687025,
    "description":"",
    "field":"",
    "id":"1d8288da-0785-4e4f-aa37-2d1db3636bc4",
    "keywords":null,
    "name":"Example capsule to execute for capsule API",
    "owner":"9b17d7b7-8b48-461a-95c6-ddb1a00a4e49",
    "published_capsule":"",
    "slug":"1576467",
    "status":"non-published"
}

List capsule computations API

GET https://{domain}codeocean.com/api/v1/capsules/{capsule_id}/computations

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain
{capsule_id}*	String	Capsule's id

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

200: OK array - computations sorted by creation date in descending order

[
    {
        "created": int64 - computation creation time
        "end_status": string - stopped,  failed, succeeded
        "has_results": boolean - indicates whether the computation has results
        "id": string - the computation internal id
        "name": string - the display name of the computation
        "run_time": int - the total run time in seconds
        "state": string - initializing,running,finalizing, completed
    }
]

Example of listing capsule computations API:

Request Example

curl --location --request GET 'https://acmecorp.codeocean.com/api/v1/capsules/1d8288da-0785-4e4f-aa37-2d1db3636bc4/computations' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your capsule's id.

Response Example

[
    {
        "created":1646690405,
        "end_status":"succeeded",
        "has_results":true,
        "id":"86a79b7f-ab60-4141-a97c-b1dbbb94decb",
        "name":"Run 6689159",
        "run_time":5,
        "state":"completed"
    },
    {    
        "created":1646690326,
        "end_status":"succeeded",
        "has_results":true,
        "id":"29fd468c-67f6-4e32-b29a-aa0f72ce5125",
        "name":"Run 6689159",
        "run_time":5,
        "state":"completed"
    }
]

Run capsule API

POST https://{domain}codeocean.com/api/v1/capsules/computations

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

Request Body

Name	Type	Description
capsule_id*	String	the id of the capsule to run
parameters	array	run parameters

200: OK array - computations sorted by creation date in descending order

{
  "id": string - the computation internal id,
  "created": float64 - computation creation time,
  "name": string - the display name of the computation,
  "run_time": int - the total run time in seconds,

  "parameters": [
    {
      "name": string parameter name,
      "value": string parameter value
    },
    {
      "name": string parameter name,
      "value": string parameter value
    }
  ],
  "result_size": float64 - result size,
  "state": string - initializing,running,finalizing, completed
}

Example of Run capsule API:

Request Example

curl --location --request POST 'https://acmecorp.codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\' \
--data-raw '{ 
    "capsule_id": "'$capsule_id'"
}'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your capsule's id.

Response Example

{
    "created":1646943238,
    "has_results":false,
    "id":"de91932c-d885-455a-9f3a-ec4a6fd95707",
    "name":"Run 6943238",
    "run_time":1,
    "state":"initializing"
}