Capsule API

Prerequisites

• Generated Token with Capsule Scope

• The Capsule ID

You can find the Capsule's ID in metadata.

Capsule Object

• id

  • string

    • the Capsule ID

• created

  • int64

    • Capsule creation time

• name

  • string

    • the Capsule display name

• status

  • string

    • non_published, submitted, publishing, published, verified

• owner

  • string

    • the Capsule owner’s ID

• slug

  • string

    • alternate Capsule ID

• original_capsule

  • 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

• published_capsule

  • Optional - string

    • published Capsule ID

• submission

  • 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

  • Optional - Array

    • Capsule versions

      • major_version - int

        • the Capsule major version

      • minor_version - int

        • the Capsule minor version

      • publish_time - int64

        • the version publishing time

      • doi - string

        • version DOI

• description

  • Optional - string

    • Capsule description

• field

  • Optional - string

    • the Capsule research field

• keywords

  • Optional - string of arrays

• article

  • Optional

    • the Capsule article info.

      • url - string

        • article URL

      • id - string

        • article ID

      • doi - string

        • article DOI

      • citation - string

        • article citation

      • state

        • in_review, published

      • name - string

        • article name

      • journal_name - string

        • articles journal name

      • publish_time - int64

        • article publish time

Get Capsule

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

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

Path Parameters

Name	Type	Description
GET*		/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

200: OK

{
    // Response
}

400: Bad Request

{
    // Response
}

401: Unauthorized

{
    // Response
}

404: Not Found

{
    // Response
}

500: Internal Server Error

{
    // Response
}

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

Capsule Object

Listing Capsule Computations

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

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

Path Parameters

Name	Type	Description
GET*		/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

200: OK

400: Bad Request

401: Unauthorized invalid API key

404: Not Found

500: Internal Server Error

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

Computation Object.

Attach/Detach Data Asset Capsules

POST https://{domain}/api/v1/capsules/{capsule_id}/data_assets

This API attaches one or many Data Assets to 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	Description
POST*		/capsules/:capsule_id/data_assets

Headers

Name	Type	Description
-u*		Authorize with Code Ocean API Secret: -u $API_SECRET :
-H*		Set this to: Content - Type: application/json
--data-raw*		JSON parameters

Request Body

Name	Type	Description
id*	string	data assets id
mount	string	Folder to mount data

200: OK with attached results

400: Bad Request

401: Unauthorized

403: Forbidden with list of not permitted Data Asset IDs

404: Not Found with list of non-existent Data Asset IDs

500: Internal Server Error

204: No Content

{
    // Response
}

Response Description

• 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

Request Example Bash

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

Request Example Python

import os, requests 


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

json_data = [
  {"id": "7fbd0ba0-9603-4e5a-9810-579207d4c1d3"}
]

response = requests.post('https://codeocean.com/api/v1/capsules/eb082456-d031-4a42-80b0-f209b8728927/data_assets',
    headers=headers,
    json=json_data,
    auth=(os.getenv('API_SECRET', ''), ''),)

Response

{
    HTTP/1.1 200 OK
    Date: Mon, 27 Nov 2023 14:12:35 GMT
    Content-Type: application/json
    Content-Length: 251
    Connection: keep-alive
    Api-Version: 2021-09-09
    Cache-Control: no-cache, no-store
    Request-Id: e510e058-90c7-4241-adcb-7c055ffa0a00
    X-Content-Type-Options: nosniff

    [
        {
            "External":false,
            "id":"052b6c02-2b81-4eca-b064-5e886c806ebe",
            "Job_id":"",
            "mount":"Sequences",
            "Mount_state":"",
            "ready":true
        },
        {
            "External":false,
            "Id":"9378e12a-f349-4f07-8f4b-9e64b8b8b514",
            "Job_id":"",
            "mount":"Reference",
            "Mount_state":"",
            "ready":true
        }
    ]
}

Detach Data Asset Capsules

DELETE https://{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	Description
POST*		/capsules/:capsule_id/data_assets

Headers

Name	Type	Description
-u*		Authorize with Code Ocean API Secret: -u $API_SECRET :
-H*		Set this to: Content - Type: application/json
--data-raw*		JSON parameters

Request Body

Name	Type	Description
id*	string	data assets id
mount	string	Folder to mount data

400: Bad Request

401: Unauthorized

403: Forbidden With list of Data Asset IDs used in App Panel

404: Not Found with list of non-existent Data Asset IDs

500: Internal Server Error

204: No Content

{
    // Response
}

Request Example Bash

curl -X DELETE \
'https://codeocean.com/api/v1/capsules/a4367940-e863-4819-afbd-1b6b9f9b1256/data_assets' \
-u \'${API_SECRET}:\' -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

import os, requests 


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

json_data = [
    "4ec22934-d75f-4385-9c52-c8e593a4234c",     
    "052b6c02-2b81-4eca-b064-5e886c806ebe",
    "9378e12a-f349-4f07-8f4b-9e64b8b8b514"
]

response = requests.delete('https://codeocean.com/api/v1/capsules/eb082456-d031-4a42-80b0-f209b8728927/data_assets',
    headers=headers,
    json=json_data,
    auth=(os.getenv('API_SECRET', ''), ''),)