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}codeocean.com/api/v1/capsules/{capsule_id}

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

Path Parameters

Name	Type	Description
PATCH*		/capsules/:capsule_id Your VPC domain

Name

Type

Description

PATCH*

/capsules/:capsule_id

Your VPC domain

Headers

Name	Type	Description
-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

Name

Type

Description

-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)
}

Request Response

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 Format

curl --location --request GET 'https://{domain}/api/v1/capsules/{capsule_id}' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\'

Request Example Bash

curl --location --request GET 'https://apps.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://apps.codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Request Example 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}codeocean.com/api/v1/capsules/{capsule_id}

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

Path Parameters

Name	Type	Description
PATCH*		/capsules/:capsule_id/computations

Name

Type

Description

PATCH*

/capsules/:capsule_id/computations

Headers

Name	Type	Description
-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

Name

Type

Description

-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

Request 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 Format

curl --location --request GET 
'https://{domain}/api/v1/capsules/{capsule_id}/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\'

Request Example Bash

curl --location --request GET 
'https://apps.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://apps.codeocean.com/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2/computations', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Request Example Response

{
  "created": 1689691505,
  "end_status": "succeeded",
  "has_results": true,
  "id": "94994ace-cd3d-4e38-9c5c-9aed12a5169d",
  "name": "Run 9691505",
  "run_time": 10,
  "state": "completed"
}

Run Capsule/Pipeline with Data Assets

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

This API allows for running of capsules or pipelines.

Path Parameters

Name	Type	Description
POST*		/computations/ Your VPC domain

Name

Type

Description

POST*

/computations/

Your VPC domain

Headers

Name	Type	Description
-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

Name

Type

Description

-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

Name	Type	Description
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

Name

Type

Description

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 Response Description

created - float64
- computation creation time
has_results - boolean
- indicates whether the computation has results
id - string
- the computation internal id
name - array
- the display name of the computation
run_time - integer
- the total run time in seconds
state - initializing, running, succeeded, failed

Request Format

curl -H "Content-Type: application/json" -u ${API_SECRET}: -X POST https://{domain}/api/v1/computations --data-raw '{
"capsule_id":"capsule_id/pipeline_id",
"data_assets": [{"id": "dataset_id", "mount": "myMount"}]

Request Example Bash

curl -H "Content-Type: application/json" -u ${API_SECRET}: -X POST https://apps.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://apps.codeocean.com/api/v1/computations', headers=headers, 
json=json_data, 
auth=(os.getenv('API_SECRET', ''), ''), 
)

Request Example Response

{
  "created": 1689691505,
  "has_results": false,
  "id": "94994ace-cd3d-4e38-9c5c-9aed12a5169d",
  "name": "Run 9691505",
  "run_time": 1,
  "state": "initializing"
}

Run Version of Capsule

POST

This API allows for running of capsules or pipelines of specific versioning.

Path Parameters

Name	Type	Description
POST *		/computations/

Name

Type

Description

POST *

/computations/

Headers

Name	Type	Description
-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

Name

Type

Description

-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

Name	Type	Description
capsule_id*	string	The identification of your capsule
version*	integer	Define the version of the capsule you wish to perform computation

Name

Type

Description

capsule_id*

string

The identification of your capsule

version*

integer

Define the version of the capsule you wish to perform computation

Request 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 Format

curl --location --request POST 'https://{domain}/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
"capsule_id": "{capsule/pipeline_id}",
"version": 1
}'

Request Example Bash

curl --location --request POST 'https://apps.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://apps.codeocean.com/api/v1/computations', headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Request Example Response

{
  "created": 1689689613,
  "has_results": false,
  "id": "9af23fd6-2957-40bf-b691-16190056c94e",
  "name": "Run 9689613",
  "run_time": 0,
  "state": "initializing"
}

Run Capsule/Pipeline

POST

This API allows for the running of capsules or pipelines.

Path Parameters

Name	Type	Description
POST*		/computations/

Name

Type

Description

POST*

/computations/

Headers

Name	Type	Description
-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

Name

Type

Description

-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

Name	Type	Description
capsule_id	string	the identification of the capsule

Name

Type

Description

capsule_id

string

the identification of the capsule

Request 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 Format

curl --location --request POST 'https://{domain}/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
"capsule_id": "{capsule/pipeline_id}"
}'

Request Example Bash

curl --location --request POST 'https://apps.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://apps.codeocean.com/api/v1/data_assets/d36665a7-ef59-4b8e-a799-bee7f83ee317', 
headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Request Example 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 Tokens NextComputation API