Capsule

Prerequisites

• Generated Access Token with Capsule scope

• The Capsule ID

You can find the Capsule's ID in metadata.

Capsule Object

• id string

  Capsule ID

• created int64 Capsule creation time

• name string

  Capsule display name

• status enum

  Status of the Capsule

  • non_release, release

• owner string

  Capsule owner’s ID

• owner_email string Capsule owner's email address

• slug string

  Alternate Capsule ID

• last_accessed int64

  Last time capsule was accessed by anyone

• description string

  Capsule description

• field string

  Capsule research field

• original_capsule dictionary (Optional)

  Original Capsule Info

  • id string

    Original Capsule id

  • major_version integer

    Original Capsule major version

  • minor_version integer Original Capsule minor version

  • name string

    Original Capsule name

  • created int64

    Original Capsule creation data

  • public boolean

    Indicates whether the original Capsule is public

• release_capsule string (Optional)

  Release Capsule ID

• submission dictionary (Optional)

  • timestamp int64

    Submission time

  • commit string

    Submission commit hash

  • verification_capsule string

    Verification Capsule ID

  • verified boolean

    Indicates whether the Capsule was verified

  • verified_timestamp int64

    Verification time

• versions dictionary (Optional)

  Capsule versions

  • major_version integer

    The Capsule major version

  • minor_version integer

    The Capsule minor version

  • release_time int64

    The version publishing time

  • doi string

    Version DOI

• tags list<string> (Optional)

• article dictionary (Optional)

  Capsule article info

  • url string

    Article URL

  • id string

    Article ID

  • doi string

    Article DOI

  • citation string

    Article citation

  • state enum

    Article state

    • in_review, published

  • name string

    Article name

  • journal_name string

    Articles journal name

  • publish_time int64

    Article publish time

• cloned_from_url string

  • URL to external Git repository linked to Capsule

Get Capsule

GET https://{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

Capsule Object

Delete Capsule

DELETE https://{codeocean-domain}/api/v1/capsules/{capsule_id}

This API allows deletion of an archived capsule/pipeline.

Path Parameters

Name	Type
capsule_id*	string

Scope

Type	Permission
Capsule	Write

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X DELETE https://${co_domain}/api/v1/capsules/${capsule_id}

Request Example Python SDK

delete_capsule = client.capsules.delete_capsule(capsule_id="242fa6b7-04dc-47f2-bdbc-5bc1e2c07feb")

Response

204 - No Content

• Returned upon successful deletion of the Capsule/Pipeline.

403 - Forbidden

• Returned in the following cases:

  • Target Capsule/Pipeline is not archived

  • User is not an either an owner of the Capsule/Pipeline or an Admin

  • Capsule/Pipeline has been Released

Get Capsule App Panel

GET https://{codeocean-domain}/api/v1/capsules/{capsule_id}/app_panel

Path Parameters

Name	Type
capsule_id*	string

Request Body (optional)

Name	Type	Description
version	integer	Version of the release capsule, latest if unspecified.

Scope

Type	Permission
Capsule	Read

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X GET https://${co_domain}/api/v1/capsules/${capsule_id}/app_panel

Request Example Python SDK

capsule_app_panel = client.capsules.get_capsule_app_panel(capsule_id="d73bbd72-c691-48fc-9996-a9b0f6a0f61c", version=2)

Response

• general (optional)

  general information

  • title string (optional)

  • instructions string (optional)

  • help_text string (optional)

• data_assets array (optional)

  input data assets

  • id string data asset ID

  • mount string data asset mount within the capsule’s/pipeline’s data folder

  • name string data asset name

  • description string (optional) data asset description

  • help_text string (optional) additional help text

  • kind - data assets type - internal, external or combined

  • accessible - boolean - indicates whether the data asset is accessible to the user

• categories array (optional) parameter categories (N/A for pipelines of capsules)

  • id string category ID

  • name string category name

  • description string (optional) category description

  • help_text string (optional) additional help text

• parameters array (optional) input parameters (N/A for pipelines of capsules)

  • category string (optional) category id from the category list, in case parameters are divided into categories

  • name string parameter label

  • param_name string (optional) parameter name

  • description string (optional) category description

  • help_text string (optional) additional help text

  • type string parameter type text, list or file

  • value_type string (optional) the type of the parameter value

  • default_value string (optional) default parameter value

  • required boolean (optional) indicates a required parameter

  • hidden boolean (optional) indicates a hidden parameter

  • minimum float64 (optional) minimum numeric value

  • maximum float64 (optional) maximum numeric value

  • pattern string (optional) value validation pattern

  • value_options array (optional) list of value options for list parameters

• results array (optional) selected result files

  • file_name string result file name

• processes array (optional) pipeline process names and their corresponding app panels (for pipelines of capsules only)

  • name string process name

  • categories array (optional) parameter categories

  • parameters array (optional) input parameters

List Capsule Computations

GET https://{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

List of Computation Object

Attach Data Assets

POST https://{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 DataAssetAttachParams

data_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:

• external boolean

  indicates whether the data asset is external

• id string

  data asset ID

• job_id string

  for internal use

• mount string

  name of folder to mount the data asset

• mount_state string

  for internal use

• ready boolean

  data asset is attached and ready for use in capsule

Detach Data Assets

DELETE https://{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,
)

Archive Capsule

PATCH https://{codeocean-domain}/api/v1/capsules/{capsule_id}/archive

This API allows for archiving of a capsule/pipeline.

Path Parameters

Name	Type
capsule_id*	string

Request Body (optional)

Name	Type	Description
archive	bool	If true will archive the capsule/pipeline, otherwise will unarchive it.

Scope

Type	Permission
Capsule	Write

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X PATCH https://${co_domain}/api/v1/capsules/${capsule_id}/archive

Request Example Python SDK

archive_capsule = client.capsules.archive_capsule(capsule_id="242fa6b7-04dc-47f2-bdbc-5bc1e2c07feb", archive=True)

Response

204 - No Content

• Returned upon successful archive/unarchive of Capsule or Pipeline.

Search Capsules/Pipelines

POST https://{codeocean-domain}/api/v1/capsules/search

POST https://{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 100).
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 CapsuleSearchParams

capsule_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"
    }
]
}

Sync Git

POST https://{codeocean-domain}/api/v1/capsules/<capsule_id>/sync

POST https://{codeocean-domain}/api/v1/pipelines/<pipeline_id>/sync

Perform a Git sync with the external Git remote of the Capsule or Pipeline.

Prerequisites

1. Capsule/Pipeline must be linked to an external Git repository.

2. User must have valid Git credentials configured.

3. User must have access to both the Capsule/Pipeline and the linked Git repository.

4. Capsule/Pipeline workspace must not be locked (e.g. when a CW session is running).

5. Capsule/Pipeline must have no uncommitted changes.

Path Parameters

Name	Type
capsule_id* or pipeline_id*	string

Response

Name	Type	Description
pushed	integer	Number of commits pushed to the external git remote.
pulled	integer	Number of commits pulled from the external git remote.
new_branch	boolean	Indicates if the current branch did not yet exist on the external git remote branch and was created by this sync.

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://${co_domain}/api/v1/capsules/${capsule_id}/sync

Request Example Python SDK

sync_results = client.capsules.sync_capsule(capsule_id="242fa6b7-04dc-47f2-bdbc-5bc1e2c07feb")

Request Example Response

{
  "pushed": 1,
  "pulled": 0,
  "new_branch": false
}