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/pipeline API

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

Create a new computation by running a capsule/pipeline

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/pipeline to run
parameters	array	run parameters (ignored when running a pipeline)
data_assets	array	id (required) - string - data asset id mount (required) - string - data asset mount folder
version	integer	the version number of a release capsule (required if capsule_id corresponds to a release capsule)

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
}

Examples of Run capsule/pipeline 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/pipeline_id'"
}'

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

Response Example

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

Request Example

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://acmecorp.codeocean.com/api/v1/computations --data-raw '{
    "capsule_id":"some-capsule/pipeline-id",
    "data_assets": [{"id": "data-asset_id", "mount": "some-folder"}]
}'

To use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, use your capsule or pipeline's id, use the data asset id of the asset you'd like to use in the computation, and replace "some-folder" with the folder name of the data asset currently attached to the capsule/pipeline.

Providing a mount folder that matches a mount folder of one of the attached data assets will substitute the attached one with the one provided here. Otherwise, the data asset will be attached in addition to the data assets that are already attached to the capsule/pipeline.

Request Example - Release Capsule

To run a specific version of a release capsule, the version number must be specified as an integer. If the "version" parameter is not specified, the latest release version will be used.

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://acmecorp.codeocean.com/api/v1/computations --data-raw '{
    "capsule_id":"release-capsule-id",
    "version": 1
}'