v2.9.0

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

All the date formats for API requests and responses are Unix (epoch) format timestamps.

Get capsule's metadata

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

Path Parameters

Headers

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

Headers

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

Headers

Request Body

{
  "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",
    "parameters": [
	    "runParam1", "runParam2" 
	],
    "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

This example shows how to run version 1 of a release capsule. 

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
}'
PreviousGetting the Code Ocean API TokensNextComputation API

Last updated