One Codex Metadata API

openapi: 3.1.0
info:
  description: The One Codex API (v1) -- programmatic access to One Codex's suite of microbial genomics data storage, analysis, and query tools.
  title: One Codex API (v1) Account Metadata API
  version: v1
servers:
- url: https://app.onecodex.com
security:
- apiKeyAuth: []
tags:
- name: Metadata
paths:
  /api/v1/metadata:
    get:
      operationId: get_metadata_instances
      parameters:
      - description: Page number. Defaults to 1. See Pagination for more details.
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int32
          type: integer
      - description: Number of requested paginated records. Defaults to 50. See Pagination for more details.
        in: query
        name: per_page
        required: false
        schema:
          default: 50
          format: int32
          type: integer
      - description: 'Optional Mongo-style JSON sort clause, e.g., `sort={"created_at": true}` to sort by created_at (descending)'
        in: query
        name: sort
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: null
      - description: 'Optional Mongo-style JSON filter clause, e.g., `where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}`'
        in: query
        name: where
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/metadata'
                type: array
          description: OK
      summary: GET metadata instances
      tags:
      - Metadata
  /api/v1/metadata/{id}:
    get:
      operationId: get_metadata_self
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metadata'
          description: OK
      summary: GET metadata
      tags:
      - Metadata
    patch:
      operationId: patch_metadata_self
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                custom:
                  anyOf:
                  - additionalProperties: true
                    type: object
                  - type: 'null'
                  description: 'Arbitrary metadata is supported as part of a custom object. custom has two constraints: (1) it must have a depth of one (i.e., no nested records); and (2) only strings, numbers, boolean, and null values are supported as values. Example: `{"lab_tech": "Linus Pauling", "amplicon_scheme": "V3-V4"}`'
                  title: Custom
                date_collected:
                  anyOf:
                  - format: date-time
                    type: string
                  - type: 'null'
                  default: null
                  description: Timestamp for when the sample was collected.
                  title: Date Collected
                date_sequenced:
                  anyOf:
                  - format: date-time
                    type: string
                  - type: 'null'
                  default: null
                  description: Timestamp for when the sample was sequenced.
                  title: Date Sequenced
                description:
                  anyOf:
                  - type: string
                  - type: 'null'
                  default: null
                  title: Description
                external_sample_id:
                  anyOf:
                  - type: string
                  - type: 'null'
                  default: null
                  description: An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.
                  example: LIMS-2024-00123
                  title: External Sample Id
                library_type:
                  anyOf:
                  - description: 'Allowed types of SampleMetadata.library_type. Also used to populate

                      form dropdown in the front-end'
                    enum:
                    - WGS
                    - Targeted/16S
                    - Other
                    title: SequencingLibraryType
                    type: string
                  - type: 'null'
                  default: null
                  description: An enum with the sample library type.
                location_lat:
                  anyOf:
                  - maximum: 90.0
                    minimum: -90.0
                    type: number
                  - type: 'null'
                  default: null
                  description: The latitude `(-90.0-90.0)` of the sample location. By convention, we recommend using this for the location in which the physical specimen was collected.
                  title: Location Lat
                location_lon:
                  anyOf:
                  - maximum: 180
                    minimum: -180
                    type: number
                  - type: 'null'
                  default: null
                  description: The longitude `(-180.0-180.0)` of the sample location.
                  title: Location Lon
                location_string:
                  anyOf:
                  - maxLength: 255
                    type: string
                  - type: 'null'
                  default: null
                  title: Location String
                name:
                  anyOf:
                  - maxLength: 255
                    type: string
                  - type: 'null'
                  default: null
                  title: Name
                platform:
                  anyOf:
                  - description: Allowed values of SampleMetadata.platform.
                    enum:
                    - 454 sequencing
                    - 454 GS FLX
                    - 454 GS FLX Titanium
                    - Illumina
                    - Illumina Genome Analyzer II
                    - Illumina HiSeq
                    - Illumina HiSeq 1500
                    - Illumina HiSeq 2000
                    - Illumina HiSeq 2500
                    - Illumina HiSeq 3000
                    - Illumina HiSeq 4000
                    - Illumina HiSeq X
                    - Illumina iSeq 100
                    - Illumina MiniSeq
                    - Illumina MiSeq
                    - Illumina NextSeq
                    - Illumina NextSeq 500
                    - Illumina NextSeq 550
                    - Illumina NovaSeq
                    - Illumina NovaSeq 5000
                    - Illumina NovaSeq 6000
                    - BGISEQ
                    - BGISEQ 50
                    - Element
                    - Element AVITI
                    - Ion
                    - Ion S5
                    - Ion S5 XL
                    - Ion PGM
                    - Ion Proton
                    - Ion Torrent
                    - Oxford Nanopore
                    - Oxford Nanopore GridION X5
                    - Oxford Nanopore MinION
                    - Oxford Nanopore PromethION
                    - PacBio
                    - PacBio RS II
                    - PacBio Sequel
                    - PacBio Sequel II System
                    - PacBio Revio
                    - PacBio Onso
                    - SOLiD
                    - Solexa Genome Analyzer
                    - Sanger
                    - Other
                    title: SequencingPlatform
                    type: string
                  - type: 'null'
                  default: null
                  description: An enum with the name of the sequencing platform.
                sample_type:
                  anyOf:
                  - description: 'Allowed values for SampleMetadata.sample_type.  Used to populate values in

                      the front-end dropdown'
                    enum:
                    - Isolate
                    - Metagenomic
                    - Other
                    title: SequencingSampleType
                    type: string
                  - type: 'null'
                  default: null
                  description: An enum with the sample type.
                starred:
                  anyOf:
                  - type: boolean
                  - type: 'null'
                  default: false
                  description: Whether the sample has been starred by the user within the One Codex web application.
                  title: Starred
              title: MetadataPatchSchema
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metadata'
          description: OK
      summary: PATCH metadata
      tags:
      - Metadata
components:
  schemas:
    metadata:
      properties:
        $uri:
          example: /api/v1/metadata/0d77065796f8d173
          pattern: ^/api/v1/metadata/[a-f0-9]{16}$
          readOnly: true
          title: $Uri
          type: string
        custom:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: 'Arbitrary metadata is supported as part of a custom object. custom has two constraints: (1) it must have a depth of one (i.e., no nested records); and (2) only strings, numbers, boolean, and null values are supported as values. Example: `{"lab_tech": "Linus Pauling", "amplicon_scheme": "V3-V4"}`'
          title: Custom
        date_collected:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Timestamp for when the sample was collected.
          title: Date Collected
        date_sequenced:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Timestamp for when the sample was sequenced.
          title: Date Sequenced
        description:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Description
        external_sample_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.
          example: LIMS-2024-00123
          title: External Sample Id
        library_type:
          anyOf:
          - description: 'Allowed types of SampleMetadata.library_type. Also used to populate

              form dropdown in the front-end'
            enum:
            - WGS
            - Targeted/16S
            - Other
            title: SequencingLibraryType
            type: string
          - type: 'null'
          default: null
          description: An enum with the sample library type.
        location_lat:
          anyOf:
          - maximum: 90.0
            minimum: -90.0
            type: number
          - type: 'null'
          default: null
          description: The latitude `(-90.0-90.0)` of the sample location. By convention, we recommend using this for the location in which the physical specimen was collected.
          title: Location Lat
        location_lon:
          anyOf:
          - maximum: 180
            minimum: -180
            type: number
          - type: 'null'
          default: null
          description: The longitude `(-180.0-180.0)` of the sample location.
          title: Location Lon
        location_string:
          anyOf:
          - maxLength: 255
            type: string
          - type: 'null'
          default: null
          title: Location String
        name:
          anyOf:
          - maxLength: 255
            type: string
          - type: 'null'
          default: null
          title: Name
        platform:
          anyOf:
          - description: Allowed values of SampleMetadata.platform.
            enum:
            - 454 sequencing
            - 454 GS FLX
            - 454 GS FLX Titanium
            - Illumina
            - Illumina Genome Analyzer II
            - Illumina HiSeq
            - Illumina HiSeq 1500
            - Illumina HiSeq 2000
            - Illumina HiSeq 2500
            - Illumina HiSeq 3000
            - Illumina HiSeq 4000
            - Illumina HiSeq X
            - Illumina iSeq 100
            - Illumina MiniSeq
            - Illumina MiSeq
            - Illumina NextSeq
            - Illumina NextSeq 500
            - Illumina NextSeq 550
            - Illumina NovaSeq
            - Illumina NovaSeq 5000
            - Illumina NovaSeq 6000
            - BGISEQ
            - BGISEQ 50
            - Element
            - Element AVITI
            - Ion
            - Ion S5
            - Ion S5 XL
            - Ion PGM
            - Ion Proton
            - Ion Torrent
            - Oxford Nanopore
            - Oxford Nanopore GridION X5
            - Oxford Nanopore MinION
            - Oxford Nanopore PromethION
            - PacBio
            - PacBio RS II
            - PacBio Sequel
            - PacBio Sequel II System
            - PacBio Revio
            - PacBio Onso
            - SOLiD
            - Solexa Genome Analyzer
            - Sanger
            - Other
            title: SequencingPlatform
            type: string
          - type: 'null'
          default: null
          description: An enum with the name of the sequencing platform.
        sample:
          description: The sample the metadata belongs to.
          properties:
            $ref:
              example: /api/v1/samples/a1b2c3d4e5f67890
              format: uri
              pattern: ^/api/v1/samples/[a-f0-9]{16}$
              type: string
          title: samples
          type: object
        sample_type:
          anyOf:
          - description: 'Allowed values for SampleMetadata.sample_type.  Used to populate values in

              the front-end dropdown'
            enum:
            - Isolate
            - Metagenomic
            - Other
            title: SequencingSampleType
            type: string
          - type: 'null'
          default: null
          description: An enum with the sample type.
        starred:
          default: false
          description: Whether the sample has been starred by the user within the One Codex web application.
          title: Starred
          type: boolean
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Timestamp for when the object was last updated on the One Codex platform, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp.
          title: Updated At
      required:
      - $uri
      - sample
      title: metadata
      type: object
  securitySchemes:
    apiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey