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:"`.