Computation API

Prerequisites

• Generated Token with Capsule Scope

• The Computation ID

The Computation ID can only be accessed from the Computation Object.

A typical use case is to use

• List Capsule Computations

• Run Computation

Both methods will have the Computation ID in the Response that can be used in Computations API for further tracking and getting results.

Computation Object

• id

  • string

    • the Computational id

• created

  • float64

    • Computation create time

• name

  • string

    • the display name of the Computation

• run_time

  • integer

    • the total run time in seconds

• cloud_workstation

  • boolean

    • indicates whether this Computation is a cloud workstation

• parameters

  • Optional - array

    • run parameters

      • name - string

        • parameter name

        • value - string

          • parameter value

• has_results

  • boolean

    • indicates whether the Computation has results

• state

  • string

    • initializing, running, finalizing, completed

• end_status

  • stopped, failed, succeeded

• data_assets

  • Optional - array

    • attached Data Assets

      • id - string

        • attached Data Asset ID

        • mount - string

          • attached Data Asset mount

  • processes

    • Optional - array

      • Pipeline processes information.

      • name

        • Pipeline process name.

      • capsule_id

        • string

          • the id of the Capsule executed in this process.

      • version

        • Optional - integer

          • Capsule version in case its a release.

      • public

        • Optional - boolean

          • indicates the Capsule is a public Code Ocean App.

      • parameters

        • Optional - array

          • run parameters

          • name - string

            • the parameter title

          • param_name - string

            • parameter name

          • value - string

            • parameter value

Get Computation

GET https://{domain}/api/v1/computations/{computations_id}

This API allows for the retrieval of information from a computational run.

Path Parameters

Name	Type	Description
GET*		/computations/:computation_id

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

Request Body

Name	Type	Description
computational_id*	string	Identification of computational run

200: OK

400: Bad Request invalid request body

401: Unauthorized

404: Not Found

500: Internal Server Error

Request Example Bash

curl --location --request GET 'https://codeocean.com/api/v1/computations/c229ed13-ec06-43d0-abd9-4d481af3f5e3' \
--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/computations/c229ed13-ec06-43d0-abd9-4d481af3f5e3', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), )

Response

Computation Object.

List Files Computation URL

GET https://{domain}/api/v1/computations/{computations_id}

This API allows for the generation of a URL to download a file from a Computation.

Path Parameters

Name	Type	Description
GET*		/computations/:computation_id

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

Request Body

Name	Type	Description
computational_id*	string	identification of the computational run

200: OK

400: Bad Request invalid request body

401: Unauthorized

404: Not Found

500: Internal Server Error

Request Example Bash

curl --location --request GET 'https://codeocean.com/api/v1/computations/9390055d-7884-4997-8dfc-88bf7445b617/results/download_url?path=GSM12345_R1_fastqc.html' \
--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/computations/9390055d-7884-4997-8dfc-88bf7445b617/results/download_url?path=GSM12345_R1_fastqc.html', headers=headers, auth=("'" + os.getenv('API_SECRET', ''), "'"), )

Response

{
    "url":"https://domain-s3resultsbucket/link/to/file"
}

Run Computation

POST https://{domain}/api/v1/computations

This API allows for the running of Capsules/Pipelines with Data Assets and Ordered or Named Parameters.

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 Resources.

Path Parameters

Name	Type	Description
POST*		/computations/

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 with parameters

Request Body

Name	Type	Description
capsule_id*	string	identification of the capsule if both capsule_id and pipeline_id are used, only the capsule id will be used
pipeline_id	string	identification of the pipeline
data_assets*	array
ID*	string	identification of the data asset to be used in the computational run
Mount	string	name of the folder to mount the dataset into position
processes	string
name*	string	pipeline process name as it appears in the main.nf script
parameters*	string	parameters expected by the capsule

200: OK

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

429: Too Many Requests

500: Internal Server Error

Run Capsule

Request Example Bash

curl --location --request POST 'https://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 = {
  "capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
} 


response = requests.post( 
'https://codeocean.com/api/v1/computations', 
headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Run Capsule with Data Assets and Ordered Parameters

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "capsule_id":"eb082456-d031-4a42-80b0-f209b8728927",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
   "parameters": [
    "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
    ]  
}'

Request Example Python

import os, requests

headers = {
 "Content-Type": "application/json"
}
json_data = {
 "capsule_id":"eb082456-d031-4a42-80b0-f209b8728927",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
   "parameters": [
    "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
    ]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)

Run Capsule with Data Assets and Named Parameters

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "capsule_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
           "mount": "Reference"
       }
   ],
   "named_parameters": [
		{
			"param_name": "NumberOfThreads",
			"value": "1"
		},
    {
			"param_name":"NumberOfFiles",
			"value": "10"
		} 
	]
}'

Request Example Python

import os, requests

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

json_data = {
 "capsule_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
           "mount": "Reference"
       }
   ],
   "named_parameters": [
		{
			"param_name": "NumberOfThreads",
			"value": "1"
		}
	]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)

Run Pipeline

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
"pipeline_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
}'

Request Example Python

import os, requests 


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


json_data = {
  "pipeline_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
} 


response = requests.put('https://codeocean.com/api/v1/data_assets/d36665a7-ef59-4b8e-a799-bee7f83ee317', 
headers=headers, json=json_data, auth=("'" + os.getenv('API_SECRET', ''), "'"), 
)

Run Pipeline with Data Assets and Ordered Capsules

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "pipeline_id":"e7a77780-b8ae-439e-89ac-fac2549da91b",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_art_simulation_illumina_1",
           "parameters": [
               "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
           ]      
       }
   ]
}'

Request Example Python

import os, requests

headers = {
 "Content-Type": "application/json"
}
json_data = {
 "pipeline_id":"e7a77780-b8ae-439e-89ac-fac2549da91b",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_art_simulation_illumina_1",
           "parameters": [
               "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
           ]      
       }
   ]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)

Run Pipeline with Data Asset and Named Capsules

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "pipeline_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_np_create_folders_test_1",
           "named_parameters": [
               {
                   "param_name": "NumFiles",
                   "value": "10"
               }
           ]
       }
   ]
}'

Request Example Python

import os, requests

headers = {
 "Content-Type": "application/json"
}
json_data = {
 "pipeline_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_np_create_folders_test_1",
           "named_parameters": [
               {
                   "param_name": "NumFiles",
                   "value": "10"
               }
           ]
       }
   ]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,

json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)

Run Pipeline with Data Assets and Ordered + Named Capsules

Request Example Bash

curl --location --request POST 'https://codeocean.com/api/v1/computations' \
--header 'Content-Type: application/json' \
-u \'${API_SECRET}:\' \
--data-raw '{
 "pipeline_id":"cd4ef788-b404-4406-8bda-76b5e41a7b8d",
 "data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_np_create_files_test_3",
           "named_parameters": [
               {
                   "param_name": "NumFiles",
                   "value": "10"
               }
           ]
       },
       {
           "name": "capsule_art_simulation_illumina_1",
           "parameters": [
               "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
           ]      
       }
   ]
}'

Request Example Python

import os, requests

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

json_data = {
"pipeline_id":"cd4ef788-b404-4406-8bda-76b5e41a7b8d",
"data_assets" : [
       {
           "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
           "mount": "Reference"
       }
   ],
 "processes": [
       {
           "name": "capsule_np_create_files_test_3",
           "named_parameters": [
               {
                   "param_name": "NumFiles",
                   "value": "10"
               }
           ]
       },
       {
           "name": "capsule_art_simulation_illumina_1",
           "parameters": [
           "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
           ]      
       }
   ]
}
response = requests.post('https://codeocean.com/api/v1/computations', headers=headers,
json=json_data,auth=(os.getenv('API_SECRET', ''), ''),)

Response

Computation Object.