Prerequisites

Generated with Capsule scope
The Capsule ID

You can find the Capsule's ID in metadata.

idstring
Capsule ID
created int64 Capsule creation time
name string
Capsule display name
statusenum
Status of the Capsule
- non_release, release
owner string
Capsule owner’s ID
slug string
Alternate Capsule ID
description string
Capsule description
fieldstring
Capsule research field
original_capsuledictionary (Optional)
Original Capsule Info
- idstring
  Original Capsule id
- major_version integer
  Original Capsule major version
- minor_version integer Original Capsule minor version
- namestring
  Original Capsule name
- createdint64
  Original Capsule creation data
- publicboolean
  Indicates whether the original Capsule is public
release_capsulestring (Optional)
Release Capsule ID
submissiondictionary (Optional)
- timestampint64
  Submission time
- commit string
  Submission commit hash
- verification_capsulestring
  Verification Capsule ID
- verifiedboolean
  Indicates whether the Capsule was verified
- verified_timestampint64
  Verification time
versionsdictionary (Optional)
Capsule versions
- major_versioninteger
  The Capsule major version
- minor_versioninteger
  The Capsule minor version
- release_timeint64
  The version publishing time
- doistring
  Version DOI
tagslist<string> (Optional)
articledictionary (Optional)
Capsule article info.
- urlstring
  Article URL
- idstring
  Article ID
- doistring
  Article DOI
- citationstring
  Article citation
- stateenum
  Article state
  - in_review, published
- namestring
  Article name
- journal_namestring
  Articles journal name
- publish_timeint64
  Article publish time
cloned_from_url string
- URL to external Git repository linked to Capsule

Get Capsule

GEThttps://{codeocean-domain}/api/v1/capsules/{capsule_id}

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

Path Parameters

Name

Type

capsule_id*

string

Scope

Type

Permission

Capsule

Read

Request Example Bash

curl https://{codeocean-domain}/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2 \ -u 'cop_d23dasd312':

Request Example Python SDK

capsule = client.capsules.get_capsule(capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2")

Response

Listing Capsule Computations

GEThttps://{codeocean-domain}/api/v1/capsules/{capsule_id}/computations

This API allows for the retrieval of Computations from a Capsule.

Path Parameters

Name

Type

capsule_id*

string

Scope

Type

Permission

Capsule

Read

Request Example Bash

curl https://{codeocean-domain}/api/v1/capsules/4bc97533-6eb4-48ac-966f-648548a756d2/computations \ -u 'cop_d23dasd312':

Request Example Python SDK

computations = client.capsules.list_computations(capsule_id="zv082356-a032-1b97-90b0-f209b8728927")

Response

Attach Data Assets

POSThttps://{codeocean-domain}/api/v1/capsules/{capsule_id}/data_assets

Path Parameters

Name

Type

capsule_id*

string

Request Body

List of DataAssetAttachParams:

Name

Type

Description

id*

string

Data Asset ID

mount

string

(Optional)

Folder to mount data

Scope

Type

Permission

Capsule

Read and Write

Data Asset

Read and Write

Request Example Bash

curl -X POST https://{codeocean-domain}/api/v1/capsules/4367940-e863-4819-afbd-1b6b9f9b1256/data_assets \ -u 'cop_d23dasd312': \ -H 'Content-Type: application/json' \ --data-raw '[ {"id": "052b6c02-2b81-4eca-b064-5e886c806ebe"}, {"id": "9378e12a-f349-4f07-8f4b-9e64b8b8b514"} ]'

Request Example Python SDK

from codeocean.data_asset import DataAssetAttachParamsdata_assets = [ DataAssetAttachParams(id="1fa0c990-3b5c-402f-ab3c-00cac6eed21e"), DataAssetAttachParams(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b", mount="Reference"),] results = client.capsules.attach_data_assets( capsule_id="zv082356-a032-1b97-90b0-f209b8728927", attach_params=data_assets,)

Response

List of DataAssetAttachResults:

externalboolean
indicates whether the data asset is external
idstring
data asset ID
job_id string
for internal use
mountstring
name of folder to mount the data asset
mount_state string
for internal use
readyboolean
data asset is attached and ready for use in capsule

Detach Data Assets

DELETEhttps://{codeocean-domain}/api/v1/capsules/{capsule_id}/data_assets

This API detaches one or many Data Assets from a Capsule/Pipeline.

Prerequisite

Before using this API call, you may need AWS Cloud Credentials configured as Secrets or an Assumable Role, if you are using Data Assets from Cloud Sources.

Path Parameters

Name

Type

capsule_id*

string

Request Body

List of Data Asset IDs to detach.

Scope

Type

Permission

Capsule

Read and Write

Data Asset

Read and Write

Request Example Bash

curl -X DELETE https://{codeocean-domain}/api/v1/capsules/a4367940-e863-4819-afbd-1b6b9f9b1256/data_assets \ -u 'cop_d23dasd312': \ -H 'Content-Type: application/json' \ --data-raw '[ "4ec22934-d75f-4385-9c52-c8e593a4234c",  "052b6c02-2b81-4eca-b064-5e886c806ebe", "9378e12a-f349-4f07-8f4b-9e64b8b8b514" ]'

Request Example Python SDK

data_assets = [ "1fa0c990-3b5c-402f-ab3c-00cac6eed21e", "1az0c240-1a9z-192b-pa4c-22bac5ffa17b",] client.capsules.detach_data_assets( capsule_id="zv082356-a032-1b97-90b0-f209b8728927", data_assets=data_assets,)

Search Capsules/Pipelines

POSThttps://{codeocean-domain}/api/v1/capsules/search

POSThttps://{codeocean-domain}/api/v1/pipelines/search

This API allows for the searching of Capsules and Pipelines in your deployment.

Request Body (all fields optional)

Name

Type or Value

Description

offset

int

Specifies the starting index for the search.

limit

int

Specifies how many items to return (up to 1000, defaults to 20).

next_token

string

Represents the token for the next page of results as provided in the previous response. If both from and next_token are set, the from parameter is ignored.

sort_order

asc, desc

Determines the result sort order. Must be provided with sort_field, otherwise ignored.

sort_field

created, name, last_accessed

Determines the field to sort by. Default when searching via filters is name. When searching via query, results are ordered by relevance to the query.

query

string

Determines the search query. Can be a free text or in the form of “name:... tag:...”

ownership

created, shared

Search Capsules by ownership. created - Only Capsules created by the user.

shared - Capsules shared with the user

** Defaults to all accessible, admins will have access to all Capsules in the system.

status

release, non_release

By default all are returned.

favorite

boolean

Search only favorite Capsules.

archived

boolean

Search only archived Capsules.

filters

list

key

string

Field key can be each of name, description, tags, any custom field key defined by the admin.

value

Field value to be included/excluded (optional).

values

Field values in case of multiple values (optional).

range

Field range to be included/excluded (only one of min/max must be set).

min

number

max

number

exclude

boolean

Whether to include/exclude the field value.

Response

Name

Type

Description

has_more

boolean

Indicates if there are more results.

next_token

number

Specifies the next page token for the next request.

results

array

Array of Capsules found.

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://${co_domain}/api/v1/capsules/search --data-raw '{"from": 0,"limit": 2,"sort_order": "desc","sort_field": "name","query": "name:my_capsule tag:my_tag","ownership": "created","status": "non_release","favorite": false,"archived": false,"filters": [{"key": "description","value": "data exploration xyz","include": true}]}'

Request Example Python SDK

from codeocean.capsule import CapsuleSearchParamscapsule_search_params = CapsuleSearchParams( limit=10, sort_order="desc", sort_field="name", ownership="private", status="non_release", archived=False, favorite=False, query="name:preprocessing tag:genomics" )capsules = client.capsules.search_capsules(capsule_search_params)

Request Example Response

{"has_more":true,"next_token":"sometoken","results":[ { "created":1728918784, "description":"data exploration xyz", "id":"68cc97f4-7472-44a9-a999-184d78182f1b", "name":"sine wave", "owner":"133192f3-7197-43ba-9570-ba0b85409396", "slug":"8678374", "status":"non_release", "tags":["python"] }, { "created":1734446547, "description":"data exploration xyz", "id":"f4ef4233-ca0d-40e6-96df-8246fdc8c681", "name":"Get utilization metrics", "owner":"133192f3-7197-43ba-9570-ba0b85409396", "slug":"9292474", "status":"non_release" }]}