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

GEThttps://{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}:\' \

{ "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

GEThttps://{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}:\' \

[ { "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

POSThttps://{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)

{ "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}'