openapi: 3.2.0
info:
  version: 1.0.0
  title: Centaur Label Reads (Opinions) Lookup API
servers:
- url: https://api.centaurlabs.com/
  description: Centaur Label APIs Production
tags:
- name: Reads (Opinions) Lookup
paths:
  /reads/public/v1/lookup:
    post:
      tags:
      - Reads (Opinions) Lookup
      description: Retrieves a list of specific reads (opinions) within a task.
      security:
      - bearerAuth: []
        ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadsLookupRequest'
      responses:
        '200':
          description: Request was successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadsLookup'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                missing_task_id:
                  value:
                    message: No task_id provided.
                invalid_task_id:
                  value:
                    message: Invalid task_id 'abc'.
                missing_read_ids:
                  value:
                    message: No read_ids provided.
                invalid_read_ids:
                  value:
                    message: Invalid read_ids 'abc'.
                read_lookup_limit_exceeded:
                  value:
                    message: Read lookup limit exceeded. Maximum allowed read_ids is 1000.
                invalid_verbose_param:
                  value:
                    message: Verbose parameter must be true or false.
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: Unauthorized
        '500':
          description: Internal server error
          content:
            text/plain:
              example: Internal Server Error.
      summary: Create reads public lookup
      x-summary-source: derived
      operationId: postReadsPublicV1Lookup
      x-operation-id-source: derived
components:
  schemas:
    ReadsLookupRequest:
      type: object
      required:
      - task_id
      - read_ids
      properties:
        task_id:
          type: integer
          description: The identifier for the task associated with the reads to be requested.
        read_ids:
          type: array
          description: The list of read (opinion) IDs to look up (maximum 1000).
          items:
            type: integer
        verbose:
          type: boolean
          description: Whether to include verbose output in the response.
    ClassAnswer:
      type: object
      properties:
        answer_class:
          type: string
          description: The label class within the answer (correct annotation, combined opinion, or labeler opinion).
        is_correct:
          type: boolean
          description: Whether the answer includes the class. Included for classification tasks only.
        geometries:
          type:
          - array
          - 'null'
          description: The segmentation for the answer class in WKT format. Included for contour segmentation tasks only.
          items:
            type: string
        mask:
          type:
          - string
          - 'null'
          description: A pre-signed URL to the segmentation for the answer class in mask (TIFF binary array) format. Included for mask segmentation tasks only.
        ranges:
          type:
          - array
          - 'null'
          description: The integer ranges for the answer class. Included for range tasks only.
          items:
            type: array
            items:
              type: integer
            minItems: 2
            maxItems: 2
        entities:
          type:
          - array
          - 'null'
          description: The entities for the answer class. Included for NER tasks only.
          items:
            type: string
        freetexts:
          type:
          - array
          - 'null'
          description: An array of freetexts with one entry (array or null) per finding.
          items:
            type:
            - array
            - 'null'
            description: An array of freetexts for one specific finding. May contain 0, 1, or multiple text entries.
            items:
              type: string
    ContentMetadata:
      type: object
      properties:
        content_id:
          type: integer
          description: An identifier for the content.
        origin:
          type: string
          description: An identifier for the file origin of the content.
        created_at:
          type: string
          description: Timestamp that content was created.
        series:
          type:
          - string
          - 'null'
          description: An identifier for the series that the content belongs to.
        series_index:
          type:
          - integer
          - 'null'
          description: The index of the content within the series (if any) that it belongs to.
        dicom_study_uid:
          type:
          - string
          - 'null'
          description: The DICOM study UID of the content.
        dicom_series_uid:
          type:
          - string
          - 'null'
          description: The DICOM series UID of the content.
        dicom_instance_uid:
          type:
          - string
          - 'null'
          description: The DICOM instance UID of the content.
    ReadsLookup:
      type: object
      properties:
        content_metadata:
          type: array
          description: The metadata for the content associated with the requested reads (opinions).
          items:
            $ref: '#/components/schemas/ContentMetadata'
        reads:
          type: array
          description: The list of reads (opinions).
          items:
            $ref: '#/components/schemas/Read'
        read_ids_not_found:
          type: array
          description: The list of read (opinion) IDs that were not found.
          items:
            type: integer
    Read:
      type: object
      properties:
        read_id:
          type: integer
          description: An identifier for the read (opinion).
        user_id:
          type: integer
          description: An identifier for the user.
        case_id:
          type: integer
          description: An identifier for the case.
        qscore:
          type: number
          description: The confidence level of the user read (opinion).
        frames:
          type: array
          description: 'The frames of the read (opinion): the primary target frame, plus one entry per context document (multi-document annotation topics only) carrying a class-agnostic finding instead of a per-label-class user_opinion.'
          items:
            type: object
            properties:
              content_id:
                type: integer
                description: An identifier for the content associated with the frame.
              user_opinion:
                type: array
                description: The portion of the read (opinion) annotation for the frame. Present on the target frame's entry only.
                items:
                  $ref: '#/components/schemas/ClassAnswer'
              categories:
                type: array
                description: The category tags assigned to this document's asset. Present on context-document entries only.
                items:
                  type: string
              freetexts:
                type: array
                description: The finding freetext recorded on this context document. Present on context-document entries only.
                items:
                  type:
                  - array
                  - 'null'
                  items:
                    type:
                    - string
                    - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
x-provenance:
  method: searched
  source: https://docs.centaurlabs.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.centaurlabs.com/reference/get_reads-public-v1-version.md
  - https://docs.centaurlabs.com/reference/get_results-public-v1-get.md
  - https://docs.centaurlabs.com/reference/get_results-public-v1-list.md
  - https://docs.centaurlabs.com/reference/get_results-public-v1-version.md
  - https://docs.centaurlabs.com/reference/get_results-public-v2-get.md
  - https://docs.centaurlabs.com/reference/get_results-public-v2-getresultsarchiveurl.md
  - https://docs.centaurlabs.com/reference/get_results-public-v2-list.md
  - https://docs.centaurlabs.com/reference/get_results-public-v2-version.md
  - https://docs.centaurlabs.com/reference/post_reads-public-v1-lookup.md
  merge:
    pages: 9
    deduped: 33
    conflicts_kept_first: 0