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
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)
}
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
Headers
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
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
}
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
Headers
Request Body
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
Headers
Request Body
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', ''), "'"),
)
Last updated