OpenAPI Specification
openapi: 3.1.0
info:
title: Code Ocean Capsules Computations API
version: v1
description: The Code Ocean REST API provides programmatic access to the Code Ocean computational research platform. It is organized around REST, accepts and returns JSON-encoded request bodies and responses, and uses standard HTTP response codes, authentication, and verbs. The API lets you manage the three core Code Ocean resources — Capsules and Pipelines (reproducible compute environments), Computations (runs of those capsules/pipelines), and Data Assets (versioned datasets) — so you can automate reproducible research and data-analysis workflows end to end.
contact:
name: Code Ocean
email: dev@codeocean.com
url: https://docs.codeocean.com/user-guide/code-ocean-api
license:
name: Proprietary
x-generated-by: API Evangelist enrichment pipeline (faithful to docs.codeocean.com)
servers:
- url: https://codeocean.com/api/v1
description: Code Ocean hosted cloud
- url: https://{domain}/api/v1
description: Code Ocean deployment (enterprise / VPC domain)
variables:
domain:
default: codeocean.com
description: Your Code Ocean deployment domain
security:
- accessToken: []
tags:
- name: Computations
description: Runs of capsules and pipelines
paths:
/computations:
post:
operationId: runCapsule
summary: Run a capsule or pipeline
description: Runs a Capsule or Pipeline, optionally attaching data assets and passing parameters. Returns the created Computation object. May return 429 when the Computation API is overloaded — back off before retrying.
tags:
- Computations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunParams'
responses:
'200':
description: Computation object
content:
application/json:
schema:
$ref: '#/components/schemas/Computation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/computations/{computation_id}:
get:
operationId: getComputation
summary: Get computation
description: Retrieves information from a computational run.
tags:
- Computations
parameters:
- $ref: '#/components/parameters/ComputationId'
responses:
'200':
description: Computation object
content:
application/json:
schema:
$ref: '#/components/schemas/Computation'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: renameComputation
summary: Rename computation
description: Renames an existing computational run.
tags:
- Computations
parameters:
- $ref: '#/components/parameters/ComputationId'
- name: name
in: query
required: true
schema:
type: string
responses:
'204':
description: Computation renamed
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteComputation
summary: Delete computation
description: Deletes a computational run, stopping it first if it is running.
tags:
- Computations
parameters:
- $ref: '#/components/parameters/ComputationId'
responses:
'204':
description: Computation deleted
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/computations/{computation_id}/results:
post:
operationId: listComputationResults
summary: List computation result files
description: Lists the result files generated by a computation. An empty path returns the /results root.
tags:
- Computations
parameters:
- $ref: '#/components/parameters/ComputationId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
path:
type: string
responses:
'200':
description: Folder listing
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/computations/{computation_id}/results/urls:
get:
operationId: getResultFileURLs
summary: Get result file URLs
description: Generates signed download and view URLs for a computation result file.
tags:
- Computations
parameters:
- $ref: '#/components/parameters/ComputationId'
- name: path
in: query
required: true
schema:
type: string
responses:
'200':
description: File URLs
content:
application/json:
schema:
$ref: '#/components/schemas/FileURLs'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Folder:
type: object
properties:
items:
type: array
items:
type: object
properties:
name:
type: string
path:
type: string
size:
type: integer
type:
type: string
enum:
- file
- folder
Error:
type: object
properties:
message:
type: string
description: Human-readable error message
Computation:
type: object
description: A run of a capsule or pipeline.
properties:
id:
type: string
name:
type: string
created:
type: integer
owner:
type: string
run_time:
type: integer
state:
type: string
enum:
- initializing
- running
- finalizing
- completed
- failed
end_status:
type: string
exit_code:
type: integer
has_results:
type: boolean
parameters:
type: array
items:
type: object
data_assets:
type: array
items:
type: object
RunParams:
type: object
description: Parameters for running a capsule or pipeline.
properties:
capsule_id:
type: string
pipeline_id:
type: string
data_assets:
type: array
items:
type: object
parameters:
type: array
items:
type: string
named_parameters:
type: array
items:
type: object
processes:
type: array
items:
type: object
nextflow_profile:
type: string
FileURLs:
type: object
properties:
download_url:
type: string
view_url:
type: string
responses:
Unauthorized:
description: No valid access token provided.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request was unacceptable (missing/invalid parameter).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too many requests — back off before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
ComputationId:
name: computation_id
in: path
required: true
description: The unique identifier of the computation.
schema:
type: string
securitySchemes:
accessToken:
type: http
scheme: basic
description: HTTP Basic authentication. Provide your Code Ocean access token (prefix `cop_`) as the basic-auth username with an empty password, e.g. `-u "cop_xxxxxxxxxx:"`.