> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycaesar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a document

> Inspect one canonical document and retrieve selected content.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/document
openapi: 3.1.0
info:
  description: >-
    Local implementation of the v1 search, document, feedback, and internal
    operational APIs.
  title: Agent Search API (Public)
  version: 0.1.0
servers:
  - description: Staging
    url: https://alpha.api.trycaesar.com
  - description: Local development
    url: http://localhost:8080
security: []
tags:
  - description: Public search APIs.
    name: Search
  - description: Public document inspection APIs.
    name: Documents
  - description: Public feedback ingestion APIs.
    name: Feedback
  - description: Asynchronous deep-research APIs.
    name: Research
  - description: Internal health, readiness, and metrics APIs.
    name: Operations
paths:
  /v1/document:
    post:
      tags:
        - Documents
      summary: Get a document
      description: Inspect one canonical document and retrieve selected content.
      operationId: get-document
      parameters:
        - description: Optional client session identifier.
          in: header
          name: X-Session-ID
          schema:
            description: Optional client session identifier.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
          description: Document payload.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Validation error.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing or invalid API key.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Insufficient prepaid balance.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: API key does not have the required scope.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Document not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Internal error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Search infrastructure unreachable.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Search infrastructure unavailable.
      security:
        - bearerApiKey: []
components:
  schemas:
    DocumentRequest:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/DocumentRequest.json
          format: uri
          readOnly: true
          type: string
        canonical_url:
          description: >-
            Canonical URL from a result's canonical_url; lookup alternative to
            doc_id. Either doc_id or canonical_url is required.
          format: uri
          type: string
        content:
          $ref: '#/components/schemas/DocumentContentRequest'
          description: >-
            Controls for returned document content: selection strategy, format,
            size cap, and continuation range.
        debug:
          additionalProperties: {}
          description: >-
            Reserved for internal evaluation harnesses; ignored for public
            callers.
          type: object
        doc_id:
          description: >-
            Canonical document identifier (UUID) from a search result's doc_id;
            stable across searches and recrawls. Either doc_id or canonical_url
            is required.
          examples:
            - 0c944fa8-4c8f-4f48-9b08-0fb2fd3438ec
          format: uuid
          type: string
        include:
          description: >-
            Sections to return. Omit it for everything available; otherwise an
            allowlist of passages, capture_history, and content (document
            metadata is always returned - send just metadata for a metadata-only
            read).
          items:
            enum:
              - metadata
              - passages
              - capture_history
              - content
            type: string
          type:
            - array
            - 'null'
        query:
          description: >-
            Query context for passage selection when content.selection is
            query_relevant.
          type: string
      type: object
    DocumentResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/DocumentResponse.json
          format: uri
          readOnly: true
          type: string
        access:
          $ref: '#/components/schemas/Access'
        capture_history:
          items:
            $ref: '#/components/schemas/CaptureHistoryEntry'
          type:
            - array
            - 'null'
        content:
          $ref: '#/components/schemas/DocumentContent'
        doc:
          $ref: '#/components/schemas/Document'
        passages:
          items:
            $ref: '#/components/schemas/Passage'
          type:
            - array
            - 'null'
        provenance:
          $ref: '#/components/schemas/DocumentProvenance'
        request_id:
          type: string
        session_id:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
        warnings:
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - request_id
        - session_id
        - access
        - doc
      type: object
    ErrorEnvelope:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/ErrorEnvelope.json
          format: uri
          readOnly: true
          type: string
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error details.
        request_id:
          description: Server request identifier.
          type: string
        type:
          description: Envelope discriminator.
          enum:
            - error
          type: string
      required:
        - type
        - request_id
        - error
      type: object
    DocumentContentRequest:
      additionalProperties: false
      properties:
        format:
          default: markdown
          description: >-
            Returned content format: markdown (default) preserves document
            structure (headings, lists, code blocks); text is plain text.
          enum:
            - text
            - markdown
          type: string
        include_offsets:
          description: >-
            When true, passages carry char_start/char_end offsets into the full
            extracted text when available, for character-precise citation.
          type: boolean
        max_chars:
          description: >-
            Optional maximum content.text characters to return. Omit it for the
            full selected content. Longer capped reads set content.truncated
            true; continue with content.range.start_char instead of retrying
            with a larger cap.
          format: int64
          minimum: 1
          type: integer
        passage_ids:
          description: >-
            Passage identifiers to return when selection is passage_ids, from a
            search result's passages or a previous read.
          items:
            type: string
          type:
            - array
            - 'null'
        range:
          $ref: '#/components/schemas/ContentRange'
          description: >-
            Continuation read: return content starting at a character offset of
            the same document.
        selection:
          default: full_document
          description: >-
            How content.text is chosen: full_document (default) returns the
            extracted document text; query_relevant returns the passages most
            relevant to query; top_passages returns the document's leading
            passages; passage_ids returns exactly content.passage_ids; none
            returns no content body.
          enum:
            - none
            - query_relevant
            - top_passages
            - passage_ids
            - full_document
          type: string
      type: object
    Access:
      additionalProperties: false
      properties:
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
      required:
        - rate_limit
      type: object
    CaptureHistoryEntry:
      additionalProperties: false
      properties:
        capture_id:
          type: string
        capture_time:
          type: string
        content_digest:
          type: string
        content_format:
          type: string
      required:
        - capture_id
        - capture_time
        - content_digest
      type: object
    DocumentContent:
      additionalProperties: false
      properties:
        char_count:
          format: int64
          type: integer
        format:
          type: string
        selection:
          type: string
        start_char:
          format: int64
          type: integer
        text:
          type: string
        truncated:
          type: boolean
      required:
        - selection
        - format
        - text
        - truncated
        - char_count
      type: object
    Document:
      additionalProperties: false
      properties:
        canonical_url:
          type: string
        content_digest:
          type: string
        doc_id:
          type: string
        first_seen_at:
          type: string
        headings:
          items:
            type: string
          type:
            - array
            - 'null'
        last_seen_at:
          type: string
        latest_capture_id:
          type: string
        meta_description:
          type: string
        published_at:
          type: string
        source_url:
          type: string
        title:
          type: string
      required:
        - doc_id
        - canonical_url
        - source_url
        - first_seen_at
        - last_seen_at
      type: object
    Passage:
      additionalProperties: false
      properties:
        char_end:
          format: int64
          type: integer
        char_start:
          format: int64
          type: integer
        doc_id:
          type: string
        ordinal:
          format: int64
          type: integer
        passage_id:
          type: string
        section_heading:
          type: string
        section_path:
          items:
            type: string
          type:
            - array
            - 'null'
        text:
          type: string
      required:
        - passage_id
        - doc_id
        - ordinal
        - text
      type: object
    DocumentProvenance:
      additionalProperties: false
      properties:
        capture_id:
          type: string
        capture_time:
          type: string
      required:
        - capture_id
        - capture_time
      type: object
    Usage:
      additionalProperties: false
      properties:
        bytes_returned:
          format: int64
          type: integer
        requests:
          format: int64
          type: integer
      required:
        - requests
        - bytes_returned
      type: object
    Warning:
      additionalProperties: false
      properties:
        code:
          type: string
        details:
          additionalProperties: {}
          type: object
        message:
          type: string
      required:
        - code
        - message
      type: object
    ErrorBody:
      additionalProperties: false
      properties:
        code:
          description: Stable machine-readable error code.
          type: string
        details:
          additionalProperties: {}
          description: Optional structured error details.
          type: object
        message:
          description: Human-readable error message.
          type: string
      required:
        - code
        - message
      type: object
    ContentRange:
      additionalProperties: false
      properties:
        capture_id:
          description: >-
            Optional capture pin; a stale_range warning is returned when the
            latest capture differs.
          type: string
        max_chars:
          description: Maximum characters for this range; overrides content.max_chars.
          format: int64
          minimum: 1
          type: integer
        start_char:
          description: Character offset to start content from.
          format: int64
          minimum: 0
          type: integer
      type: object
    RateLimit:
      additionalProperties: false
      properties:
        limit_rps:
          format: int64
          type: integer
        remaining:
          format: int64
          type: integer
        reset_at:
          type: string
      required:
        - limit_rps
        - remaining
        - reset_at
      type: object
  securitySchemes:
    bearerApiKey:
      bearerFormat: API key
      scheme: bearer
      type: http

````