Antfly Documents API

openapi: 3.2.0
info:
  title: Antfly Public Documents API
  version: v1alpha1
  description: Joined public contract for the Antfly server. Antfly APIs are served under `/db/v1`, auth APIs under `/auth/v1`, inference APIs under `/ai/v1`, ML prediction APIs under `/ml/v1`, and extension lifecycle APIs under `/extensions/v1`.
servers:
- url: /
security:
- BasicAuth: []
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Documents
paths:
  /ai/v1/read/jobs:
    post:
      operationId: createReadDocumentJob
      summary: Submit a durable read job
      description: Unified Antfly API only. Persists the request before returning. Jobs continue after the submitting client disconnects. Sources and accepted stages are immutable snapshots; ambiguous calls remain charged on retry. Retention is absolute and is not extended by polling or resuming.
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InferenceDocumentJobRequest'
      responses:
        '202':
          description: Durable job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/read/jobs/{job_id}:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getReadDocumentJob
      summary: Get principal-scoped document job status
      tags:
      - Documents
      responses:
        '200':
          description: Job status without source bytes or internal artifact references
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/read/jobs/{job_id}/result:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: resultReadDocumentJob
      summary: Atomic final response
      description: Atomic final response; unavailable until the whole job succeeds
      tags:
      - Documents
      responses:
        '200':
          description: Atomic final response; unavailable until the whole job succeeds
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/read/jobs/{job_id}/events:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: eventsReadDocumentJob
      summary: Server-sent committed event groups with stable numeric IDs.
      description: Server-sent committed event groups with stable numeric IDs. Last-Event-ID resumes after that sequence. Disconnecting only detaches the subscriber.
      tags:
      - Documents
      responses:
        '200':
          description: Server-sent committed event groups with stable numeric IDs. Last-Event-ID resumes after that sequence. Disconnecting only detaches the subscriber.
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/read/jobs/{job_id}/resume:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: resumeReadDocumentJob
      summary: Requeue an interrupted job without resetting its budget or retention
      tags:
      - Documents
      responses:
        '200':
          description: Requeue an interrupted job without resetting its budget or retention
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/read/jobs/{job_id}/cancel:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: cancelReadDocumentJob
      summary: Fence the current attempt and cancel the job
      tags:
      - Documents
      responses:
        '200':
          description: Fence the current attempt and cancel the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs:
    post:
      operationId: createExtractDocumentJob
      summary: Submit a durable extract job
      description: Unified Antfly API only. Persists the request before returning. Jobs continue after the submitting client disconnects. Sources and accepted stages are immutable snapshots; ambiguous calls remain charged on retry. Retention is absolute and is not extended by polling or resuming.
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InferenceDocumentJobRequest'
      responses:
        '202':
          description: Durable job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs/{job_id}:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getExtractDocumentJob
      summary: Get principal-scoped document job status
      tags:
      - Documents
      responses:
        '200':
          description: Job status without source bytes or internal artifact references
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs/{job_id}/result:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: resultExtractDocumentJob
      summary: Atomic final response
      description: Atomic final response; unavailable until the whole job succeeds
      tags:
      - Documents
      responses:
        '200':
          description: Atomic final response; unavailable until the whole job succeeds
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs/{job_id}/events:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: eventsExtractDocumentJob
      summary: Server-sent committed event groups with stable numeric IDs.
      description: Server-sent committed event groups with stable numeric IDs. Last-Event-ID resumes after that sequence. Disconnecting only detaches the subscriber.
      tags:
      - Documents
      responses:
        '200':
          description: Server-sent committed event groups with stable numeric IDs. Last-Event-ID resumes after that sequence. Disconnecting only detaches the subscriber.
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs/{job_id}/resume:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: resumeExtractDocumentJob
      summary: Requeue an interrupted job without resetting its budget or retention
      tags:
      - Documents
      responses:
        '200':
          description: Requeue an interrupted job without resetting its budget or retention
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
  /ai/v1/extract/jobs/{job_id}/cancel:
    parameters:
    - name: job_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: cancelExtractDocumentJob
      summary: Fence the current attempt and cancel the job
      tags:
      - Documents
      responses:
        '200':
          description: Fence the current attempt and cancel the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceDocumentJob'
        '401':
          description: Authentication is enabled and valid credentials were not supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
        '503':
          description: The unified Antfly server also returns this status when authentication is enabled but its backend is not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferenceError'
components:
  schemas:
    InferenceDocumentJob:
      type: object
      required:
      - id
      - operation
      - state
      - attempt
      - sequence
      - expires_at_ms
      - usage
      properties:
        id:
          type: string
        operation:
          type: string
          enum:
          - read
          - extract
        state:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - cancelled
        attempt:
          type: integer
          format: int64
        sequence:
          type: integer
          format: int64
        expires_at_ms:
          type: integer
          format: int64
        usage:
          type: object
          additionalProperties: true
        error:
          type: string
    InferenceError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Stable machine-readable error code
        message:
          type: string
          description: Human-readable error description
        reason:
          type: string
          description: Machine-readable capacity source when the failure is retryable
          enum:
          - inference_capacity
          - inference_admission
        retryable:
          type: boolean
          x-go-type-skip-optional-pointer: false
          description: Whether retrying the request may succeed
        retry_after_ms:
          type: integer
          minimum: 0
          description: Minimum retry delay in milliseconds
        input_index:
          type: integer
          minimum: 0
          x-go-type-skip-optional-pointer: false
          description: Input whose atomic extraction validation or decoding failed, when known
        stage:
          type: string
          description: Extraction failure stage, when known
    InferenceDocumentJobRequest:
      type: object
      additionalProperties: false
      required:
      - request
      description: Durable document execution on the unified Antfly API. Requires configured durable job storage and local inference orchestration. The request uses the ordinary read or extract schema. Credentials must use server connections, environment variables, or secret references.
      properties:
        request:
          type: object
          additionalProperties: true
        retention_seconds:
          type: integer
          minimum: 60
          maximum: 604800
          default: 86400
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Antfly
  tags:
  - cluster_management
  - table_management
  - data_operations
  - query_operations
  - index_management
- name: Auth
  tags:
  - User
  - Permission
  - ApiKey
  - RowFilter
- name: Inference
  tags: []
- name: Extensions
  tags:
  - Packages
  - Installed