v2.15.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

Get Capsule Metadata

GET https://{domain}/api/v1/capsules/{capsule_id}

This API allows for the retrieval of the metadata for your capsule.

Path Parameters

NameTypeDescription

PATCH*

/capsules/:capsule_id

Your VPC domain

Headers

NameTypeDescription

-u*

Authorize with Code Ocean API Secret: -u $API_SECRET

This is setting the "Authorization Basic" base64string header

-H*

Set this to: Content - Type: application/json

{
    "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)
}
Response Description

  • created - float64

    • data asset creation time

  • description - string

    • data asset description

  • field - string

    • field of research

  • id - integer

    • metadata id

  • keywords - string/list

    • associated keywords

  • name - string

    • name of the data asset

  • owner - string

    • identification ID of the owner

  • published capsule - boolean

    • value indicates whether this capsule is published

  • slug - integer

    • unkown

  • status - boolean

    • indicates the status of this capsule

Request Example Bash
curl --location --request GET 'https://codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\'
Request Example Python
import os, requests 


headers = {
  "Content-Type": "application/json"
} 


response = requests.get( 'https://codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)
Response
{
  "cloned_from_url": "",
  "created": 1673385764,
  "description": "This tool takes an alignment of reads or fragments as input (BAM file) and generates a coverage track (bigWig or bedGraph) as output. The coverage is calculated as the number of reads per bin, where bins are short consecutive counting windows of a defined size. It is possible to extended the length of the reads to better reflect the actual fragment length. bamCoverage offers normalization by scaling factor, Reads Per Kilobase per Million mapped reads (RPKM), counts per million (CPM), bins per million mapped reads (BPM) and 1x depth (reads per genome coverage, RPGC).\n\nSource : https://deeptools.readthedocs.io/en/develop/content/tools/bamCoverage.html",
  "field": "Bioinformatics",
  "id": "4bc97533-6eb4-48ac-966f-648548a756d2",
  "keywords": [
    "ChIP",
    "Normalization"
  ],
  "name": "deepTools-bamCoverage",
  "owner": "467ef120-2c93-42eb-8865-5866004243bf",
  "published_capsule": "",
  "slug": "7607289",
  "status": "non-published"
}

Listing Capsule Computations

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

This API allows for the retrieval of the computations runs of a capsule.

Path Parameters

NameTypeDescription

PATCH*

/capsules/:capsule_id/computations

Headers

NameTypeDescription

-u*

Authorize with Code Ocean API Secret: -u $API_SECRET

This is setting the "Authorization Basic" base64string header

-H

Set this to: Content - Type: application/json

Response Description

  • created - float64

    • computation creation time

  • end_results - failed, succeeded

    • if any results are available

  • has_results - boolean

    • does the computation have results

  • id - string

    • name of the run

  • name - string

    • the computation internal id

  • run_time - integer

    • the total run time in seconds

  • state - initializing, running, finaliing, completed

    • state of the computation

Request Example Bash
curl --location --request GET 'https://codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\'
Request Example Python
import os, requests 


headers = {
  "Content-Type": "application/json"
} 


response = requests.get('https://codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2/computations', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)
Response
{
    "created":1704745212,
    "data_assets":[
        {"id":"2a40cd02-395a-4c44-8b41-0bd4508cedb8","mount":"Annotation"},
      {"id":"7fbd0ba0-9603-4e5a-9810-579207d4c1d3","mount":"Example_paired_end_small"}
            ],
            "end_status":"succeeded",
            "has_results":"true",
            "id":"a0f93da1-4303-4572-9c00-182fd8f3c08a",
            "name":"Run 4745212",
            "run_time":8,
            "state":"completed"
}

Run Capsule

POST https://{domain}/api/v1/computations

This API allows for the running of capsules.

Path Parameters

NameTypeDescription

POST*

/computations/

Headers

NameTypeDescription

-u*

Authorize with Code Ocean API Secret:

-u $API_SECRET :

This is setting the "Authorization Basic" base64string header

-H*

Set this to: Content - Type: application/json

--data-raw*

JSON data with new or updated permissions

Request Body

NameTypeDescription

capsule_id*

string

the identification of the capsule

Response Description

  • created - string

    • the data asset creation time in seconds from unix epoch

  • has_results - boolean

    • if any results are available

  • id - string

    • the computation internal id

  • name - array

    • name of the run

  • run_time - integer

    • unknown

  • state - initializing

    • unknown

Request Example Bash
curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
"capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
}'
Request Example Python
import os, requests 

headers = {
  "Content-Type": "application/json"
}


json_data = {
  "name": "Modified The Name",
  "description": "a new description from the API!",
  "tags": [
    "I",
    "Am",
    "New"
  ],
  "mount": "NewMount"
} 


response = requests.put( 
'https://codeocean.com/api/v1/data_assets/d36665a7-ef59-4b8e-a799-bee7f83ee317', 
headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)
Response
{
  "created": 1689689613,
  "has_results": false,
  "id": "9af23fd6-2957-40bf-b691-16190056c94e",
  "name": "Run 9689613",
  "run_time": 0,
  "state": "initializing"
}

Run Capsule with Data Assets

POST https://{domain}/api/v1/computations

This API allows for running of capsules or pipelines.

Path Parameters

NameTypeDescription

POST*

/computations/

Your VPC domain

Headers

NameTypeDescription

-u*

Authorize with Code Ocean API Secret: -u $API_SECRET :

This is setting the "Authorization Basic" base64string header

-H*

Set this to: Content - Type: application/json

--data-raw*

JSON data with new or updated permissions

Request Body

NameTypeDescription

capsule_id*

string

the identification of the data asset to be used in computational run the id of the capsule/pipeline to run

data_assets*

string

id*

string

the identification of the data asset to be used in computational run

mount*

string

the name of the folder you wish to mount this dataset into position

{
  "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
}
Request Example Bash
curl -H "Content-Type: application/json" -u ${API_SECRET}: -X POST https://codeocean.com/api/v1/computations --data-raw '{
"capsule_id":"4bc97533-6eb4-48ac-966f-648548a756d2",
"data_assets": [{"id": "bf8cf993-a583-495c-bebd-2f38f81d1ea1", "mount": "Alignment"}]
}'
Request Example Python
import os, requests 


headers = {
  "Content-Type": "application/json"
}
 
json_data = {
  "capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2",
  "data_assets": {
    "id": "bf8cf993-a583-495c-bebd-2f38f81d1ea1",
    "mount": "Alignment"
  }
}
 
response = requests.post( 'https://codeocean.com/api/v1/computations', headers=headers, 
json=json_data, 
auth=(os.getenv('API_SECRET', ''), ''), 
)
Response
{
  "created": 1689691505,
  "has_results": false,
  "id": "94994ace-cd3d-4e38-9c5c-9aed12a5169d",
  "name": "Run 9691505",
  "run_time": 1,
  "state": "initializing"
}

Run Capsule with Data Assets & Parameters

POST https://{domain}/api/v1/computations

This API allows for running of capsules or pipelines.

Path Parameters

NameTypeDescription

POST*

/computations/

Your VPC domain

Headers

NameTypeDescription

-u*

Authorize with Code Ocean API Secret: -u $API_SECRET :

This is setting the "Authorization Basic" base64string header

-H*

Set this to: Content - Type: application/json

--data-raw*

JSON data with new or updated permissions

Request Body

NameTypeDescription

capsule_id*

string

the identification of the data asset to be used in computational run the id of the capsule/pipeline to run

data_assets*

string

id*

string

the identification of the data asset to be used in computational run

mount*

string

the name of the folder you wish to mount this dataset into position

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

Ordered Parameters

Request Example Bash
curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "capsule_id":"eb082456-d031-4a42-80b0-f209b8728927",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
   "parameters": [
    "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
    ]  
}'
Request Example Python
import os, requests

headers = {
 "Content-Type": "application/json"
}
json_data = {
 "capsule_id":"eb082456-d031-4a42-80b0-f209b8728927",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
   "parameters": [
    "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
    ]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)
Response
{
    "created":1701872878,
    "Data_assets":
    [
        {
            "Id":"eeefcc52-b445-4e3c-80c5-0e65526cd712",
            "mount":"Reference"
        }
    ],
    "Has_results":false,
    "Id":"3e4041e3-1970-4bc8-9d55-56887d4c5375",
    "name":"Run With Parameters 1872878",
    "Run_time":1,
    "state":"initializing"
}

Named Parameters

Request Example Bash
curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "capsule_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
           "mount": "Reference"
       }
   ],
   "named_parameters": [
		{
			"param_name": "NumberOfThreads",
			"value": "1"
		},
    {
			"param_name":"NumberOfFiles",
			"value": "10"
		} 
	]
}'
Request Example Python
import os, requests

headers = {
 "Content-Type": "application/json"
}

json_data = {
 "capsule_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
           "mount": "Reference"
       }
   ],
   "named_parameters": [
		{
			"param_name": "NumberOfThreads",
			"value": "1"
		},
    {
			"param_name":"NumberOfFiles",
			"value": "10"
		} 
	]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)
Response
{
    "created":1701872878,
    "Data_assets":
    [
        {
            "Id":"9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
            "mount":"Reference"
        }
    ],
    "Has_results":false,
    "Id":"3e4041e3-1970-4bc8-9d55-56887d4c5375",
    "name":"Run With Parameters 1872878",
    "Run_time":1,
    "state":"initializing"
}

Run Version of Capsule

Response Description

  • created - string

    • unknown

  • has_results - boolean

    • if any results are available

  • id - string

    • identification string of capsule

  • name - array

    • name of the run

  • run_time - integer

    • unknown

  • state - initializing

    • unknown

Request Example Bash
curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
"capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2",
"version": 1
}'
Request Example Python
import os, requests 


headers = {
  "Content-Type": "application/json"
} 


json_data = {
  "capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2",
  "version": 1
}
 
response = requests.post( 'https://codeocean.com/api/v1/computations', headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)
Response
{
  "created": 1689689613,
  "has_results": false,
  "id": "9af23fd6-2957-40bf-b691-16190056c94e",
  "name": "Run 9689613",
  "run_time": 0,
  "state": "initializing"
}
PreviousGetting the Code Ocean API TokensNextPipeline API

Last updated