openapi: 3.1.0
info:
  title: Code Ocean Capsules Data Assets 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: Data Assets
  description: Versioned datasets and result data
paths:
  /data_assets:
    post:
      operationId: createDataAsset
      summary: Create data asset
      description: Creates a Data Asset from an S3 bucket or from a computation's results.
      tags:
      - Data Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataAssetParams'
      responses:
        '200':
          description: Data asset object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAsset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data_assets/{data_asset_id}:
    get:
      operationId: getDataAsset
      summary: Get data asset
      description: Retrieves metadata for a specific Data Asset.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      responses:
        '200':
          description: Data asset object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAsset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDataAssetMetadata
      summary: Update data asset metadata
      description: Updates a Data Asset's name, description, tags, mount and custom metadata.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - description
              - tags
              - mount
              properties:
                name:
                  type: string
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                mount:
                  type: string
                custom_metadata:
                  type: object
      responses:
        '200':
          description: Data asset object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAsset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDataAsset
      summary: Delete data asset
      description: Deletes a Data Asset.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      responses:
        '204':
          description: Data asset deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /data_assets/{data_asset_id}/archive:
    patch:
      operationId: archiveDataAsset
      summary: Archive or unarchive a data asset
      description: Archives or unarchives a Data Asset.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      - name: archive
        in: query
        required: true
        schema:
          type: boolean
      responses:
        '204':
          description: Archive state updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /data_assets/search:
    post:
      operationId: searchDataAssets
      summary: Search data assets
      description: Searches Data Assets with filtering, sorting and cursor pagination.
      tags:
      - Data Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchParams'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /data_assets/{data_asset_id}/permissions:
    post:
      operationId: updateDataAssetPermissions
      summary: Update data asset permissions
      description: Updates user, group and everyone access permissions for a Data Asset.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - users
              - groups
              - everyone
              properties:
                users:
                  type: array
                  items:
                    type: object
                groups:
                  type: array
                  items:
                    type: object
                everyone:
                  type: string
                share_assets:
                  type: boolean
      responses:
        '204':
          description: Permissions updated
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /data_assets/{data_asset_id}/transfer:
    post:
      operationId: transferDataAsset
      summary: Transfer data asset
      description: Admin-only. Transfers a Data Asset's files to a different S3 storage location.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                target:
                  type: object
                  properties:
                    aws:
                      type: object
                      properties:
                        bucket:
                          type: string
                        prefix:
                          type: string
                force:
                  type: boolean
      responses:
        '200':
          description: Transfer started
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /data_assets/{data_asset_id}/files:
    post:
      operationId: listDataAssetFiles
      summary: List data asset files
      description: Lists files internal to a Data Asset, optionally under a folder path.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      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'
  /data_assets/{data_asset_id}/files/urls:
    get:
      operationId: getDataAssetFileURLs
      summary: Get data asset file URLs
      description: Generates signed download and view URLs for a file within a Data Asset.
      tags:
      - Data Assets
      parameters:
      - $ref: '#/components/parameters/DataAssetId'
      - 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
    DataAssetParams:
      type: object
      description: Parameters for creating a data asset.
      required:
      - name
      - mount
      - tags
      - source
      properties:
        name:
          type: string
        description:
          type: string
        mount:
          type: string
        tags:
          type: array
          items:
            type: string
        source:
          type: object
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message
    DataAsset:
      type: object
      description: A versioned dataset or captured result data.
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        created:
          type: integer
        type:
          type: string
          enum:
          - dataset
          - result
        mount:
          type: string
        state:
          type: string
        tags:
          type: array
          items:
            type: string
        custom_metadata:
          type: object
    SearchResults:
      type: object
      description: Cursor-paginated search results.
      properties:
        has_more:
          type: boolean
        next_token:
          type: string
        results:
          type: array
          items:
            type: object
    FileURLs:
      type: object
      properties:
        download_url:
          type: string
        view_url:
          type: string
    SearchParams:
      type: object
      description: Search request with filtering, sorting and cursor pagination.
      properties:
        offset:
          type: integer
        limit:
          type: integer
        next_token:
          type: string
        sort_order:
          type: string
          enum:
          - asc
          - desc
        sort_field:
          type: string
        query:
          type: string
        ownership:
          type: string
        status:
          type: string
        type:
          type: string
        origin:
          type: string
        favorite:
          type: boolean
        archived:
          type: boolean
        filters:
          type: array
          items:
            type: object
  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'
    Forbidden:
      description: The access token doesn't have permission to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    DataAssetId:
      name: data_asset_id
      in: path
      required: true
      description: The unique identifier of the data asset.
      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:"`.