Nace Ai public-api API

openapi: 3.1.0
info:
  title: NDI Service health public-api API
  description: Nace Document Intelligence Service API
  version: 0.1.0
tags:
- name: public-api
paths:
  /api/v1/parse_async:
    post:
      tags:
      - public-api
      summary: Parse Async
      description: Start a parse job; returns a ``job_id`` to poll.
      operationId: parse_async_api_v1_parse_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseJobRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Idempotent replay — a job with this idempotency_key already exists; body is its current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
      security:
      - APIKeyHeader: []
  /api/v1/parse:
    post:
      tags:
      - public-api
      summary: Parse Sync
      description: Parse a document and wait for the result (small documents; use /parse_async for large ones).
      operationId: parse_sync_api_v1_parse_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: number
          maximum: 300.0
          minimum: 1.0
          description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
          default: 120.0
          title: Timeout Seconds
        description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
        '202':
          description: The job started but no sync capacity was available; poll GET /jobs/{job_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '408':
          description: The job did not finish within timeout_seconds; poll GET /jobs/{job_id}.
  /api/v1/upload:
    post:
      tags:
      - public-api
      summary: Upload File
      description: 'Stage a document and return an opaque ``file_id``.


        Pass ``ndi://file/<file_id>`` as ``source_url`` on any action endpoint.

        Upload once, reuse across parse → categorize / ground.


        ``expires_at`` is the advertised handle lifetime (managed staging lifecycle

        minus a safety margin). For ``byo_bucket`` tenants the same window is

        advertised for contract consistency, but actual object deletion follows

        the tenant''s own bucket lifecycle configuration.'
      operationId: upload_file_api_v1_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_file_api_v1_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Upload exceeds NDI_MAX_UPLOAD_BYTES.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - APIKeyHeader: []
  /api/v1/ground_async:
    post:
      tags:
      - public-api
      summary: Ground Async
      description: 'Start a ground job: locate values inside a document.'
      operationId: ground_async_api_v1_ground_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundJobRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Idempotent replay — a job with this idempotency_key already exists; body is its current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
      security:
      - APIKeyHeader: []
  /api/v1/ground:
    post:
      tags:
      - public-api
      summary: Ground Sync
      description: Ground values in a document and wait for the result.
      operationId: ground_sync_api_v1_ground_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: number
          maximum: 300.0
          minimum: 1.0
          description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
          default: 120.0
          title: Timeout Seconds
        description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
        '202':
          description: The job started but no sync capacity was available; poll GET /jobs/{job_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '408':
          description: The job did not finish within timeout_seconds; poll GET /jobs/{job_id}.
  /api/v1/categorize_async:
    post:
      tags:
      - public-api
      summary: Categorize Async
      description: 'Start a categorize job: classify document segments/sheets against a taxonomy.'
      operationId: categorize_async_api_v1_categorize_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategorizeJobRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Idempotent replay — a job with this idempotency_key already exists; body is its current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
      security:
      - APIKeyHeader: []
  /api/v1/categorize:
    post:
      tags:
      - public-api
      summary: Categorize Sync
      description: Categorize a document and wait for the result.
      operationId: categorize_sync_api_v1_categorize_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: number
          maximum: 300.0
          minimum: 1.0
          description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
          default: 120.0
          title: Timeout Seconds
        description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategorizeJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
        '202':
          description: The job started but no sync capacity was available; poll GET /jobs/{job_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '408':
          description: The job did not finish within timeout_seconds; poll GET /jobs/{job_id}.
  /api/v1/extract_async:
    post:
      tags:
      - public-api
      summary: Extract Async
      description: 'Start an extract job: pull schema-shaped structured data out of a document.'
      operationId: extract_async_api_v1_extract_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractJobRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Idempotent replay — a job with this idempotency_key already exists; body is its current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
      security:
      - APIKeyHeader: []
  /api/v1/extract:
    post:
      tags:
      - public-api
      summary: Extract Sync
      description: Extract structured data from a document and wait for the result.
      operationId: extract_sync_api_v1_extract_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: number
          maximum: 300.0
          minimum: 1.0
          description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
          default: 120.0
          title: Timeout Seconds
        description: Max seconds to wait before returning 408 (the job keeps running; poll GET /jobs/{job_id}).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
        '202':
          description: The job started but no sync capacity was available; poll GET /jobs/{job_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '408':
          description: The job did not finish within timeout_seconds; poll GET /jobs/{job_id}.
  /api/v1/jobs:
    get:
      tags:
      - public-api
      summary: List Jobs
      description: List the tenant's jobs, newest first (summaries only — no result payloads).
      operationId: list_jobs_api_v1_jobs_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Jobs per page.
          default: 50
          title: Limit
        description: Jobs per page.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: '``next_cursor`` from the previous page; omit for the newest page.'
          title: Cursor
        description: '``next_cursor`` from the previous page; omit for the newest page.'
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(pending|running|succeeded|failed)$
          - type: 'null'
          description: Optional status filter.
          title: Status
        description: Optional status filter.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
  /api/v1/jobs/{job_id}:
    get:
      tags:
      - public-api
      summary: Get Job
      description: Return the current state of a job (tenant-scoped; other tenants see 404).
      operationId: get_job_api_v1_jobs__job_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request Entity Too Large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:


# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nace-ai/refs/heads/main/openapi/nace-ai-public-api-api-openapi.yml