# Generated by `just openapi-export`; do not edit by hand.
# FastAPI routes and Pydantic models are the source of truth.
openapi: 3.1.0
info:
  title: ParseHawk API
  summary: Local-first document extraction API
  description: Turn PDFs, images, scans, Markdown, and text into validated JSON. ParseHawk is self-hosted
    and exposes the same local API used by its CLI and web UI.
  contact:
    name: ParseHawk support
    url: https://github.com/parsehawk/parsehawk/issues
  license:
    name: Apache License 2.0
    identifier: Apache-2.0
  version: 0.2.1
servers:
- url: http://127.0.0.1:8000
  description: Default local ParseHawk API
paths:
  /health:
    get:
      tags:
      - health
      summary: Check API health
      description: Return a lightweight liveness response without accessing the database or model runtime.
      operationId: getHealth
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /:
    get:
      tags:
      - health
      summary: Discover the API
      description: Return a welcome message and the canonical developer documentation URL.
      operationId: getApiRoot
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/files:
    get:
      tags:
      - files
      summary: List files
      description: List metadata for every uploaded and built-in example file.
      operationId: listFiles
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FileResponse'
                type: array
                title: Response Listfiles
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
    post:
      tags:
      - files
      summary: Upload a file
      description: Store a document locally and return metadata for use in extraction jobs.
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_uploadFile'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-codeSamples:
      - lang: bash
        label: curl
        source: "API=\"${PARSEHAWK_API_URL:-http://127.0.0.1:8000}\"\ncurl --fail --silent --show-error\
          \ \\\n  --request POST \"$API/v1/files\" \\\n  --form \"upload=@document.pdf;type=application/pdf\"\
          \ | jq ."
  /v1/files/{file_id}:
    get:
      tags:
      - files
      summary: Get file metadata
      description: Retrieve metadata for one stored file without returning its content.
      operationId: getFile
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable file identifier.
          title: File Id
        description: Immutable file identifier.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - files
      summary: Delete a file
      description: Delete one stored file and its local content.
      operationId: deleteFile
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable file identifier.
          title: File Id
        description: Immutable file identifier.
      responses:
        '204':
          description: Successful Response
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/files/{file_id}/content:
    get:
      tags:
      - files
      summary: Download file content
      description: Stream the original stored bytes with their recorded media type and filename.
      operationId: downloadFileContent
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable file identifier.
          title: File Id
        description: Immutable file identifier.
      responses:
        '200':
          description: Original file bytes.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
      - lang: bash
        label: curl
        source: "API=\"${PARSEHAWK_API_URL:-http://127.0.0.1:8000}\"\ncurl --fail --silent --show-error\
          \ \\\n  \"$API/v1/files/file_.../content\" \\\n  --output document.pdf"
  /v1/extractors:
    get:
      tags:
      - extractors
      summary: List extractors
      description: List custom and built-in extraction definitions.
      operationId: listExtractors
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ExtractorResponse'
                type: array
                title: Response Listextractors
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
    post:
      tags:
      - extractors
      summary: Create an extractor
      description: Create a reusable extraction definition from instructions, a schema, and optional examples.
      operationId: createExtractor
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExtractorRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/extractors/{extractor_ref}:
    get:
      tags:
      - extractors
      summary: Get an extractor
      description: Retrieve an extractor by immutable ID or stable name.
      operationId: getExtractor
      parameters:
      - name: extractor_ref
        in: path
        required: true
        schema:
          type: string
          description: Extractor ID or stable name.
          title: Extractor Ref
        description: Extractor ID or stable name.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - extractors
      summary: Update an extractor
      description: Partially update a custom extractor while preserving omitted fields.
      operationId: updateExtractor
      parameters:
      - name: extractor_ref
        in: path
        required: true
        schema:
          type: string
          description: Extractor ID or stable name.
          title: Extractor Ref
        description: Extractor ID or stable name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExtractorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
    put:
      tags:
      - extractors
      summary: Create or replace an extractor
      description: Create a named extractor when absent or replace its complete definition when present.
      operationId: upsertExtractor
      parameters:
      - name: extractor_ref
        in: path
        required: true
        schema:
          type: string
          description: Stable extractor name.
          title: Extractor Ref
        description: Stable extractor name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertExtractorRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
    delete:
      tags:
      - extractors
      summary: Delete an extractor
      description: Delete a custom extractor. Built-in extractors cannot be deleted.
      operationId: deleteExtractor
      parameters:
      - name: extractor_ref
        in: path
        required: true
        schema:
          type: string
          description: Extractor ID or stable name.
          title: Extractor Ref
        description: Extractor ID or stable name.
      responses:
        '204':
          description: Successful Response
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/providers:
    get:
      tags:
      - providers
      summary: List providers
      description: List all fixed provider slots and their non-secret configuration.
      operationId: listProviders
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ProviderResponse'
                type: array
                title: Response Listproviders
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/providers/{name}:
    get:
      tags:
      - providers
      summary: Get a provider
      description: Retrieve non-secret configuration for one provider.
      operationId: getProvider
      parameters:
      - name: name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
          description: Stable provider name.
        description: Stable provider name.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
    patch:
      tags:
      - providers
      summary: Configure a provider
      description: Update a provider endpoint, non-secret settings, or securely stored API key.
      operationId: configureProvider
      parameters:
      - name: name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
          description: Stable provider name.
        description: Stable provider name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureProviderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/providers/{name}/models:
    get:
      tags:
      - providers
      summary: List provider models
      description: Query the configured provider and return the model identifiers it currently advertises.
      operationId: listProviderModels
      parameters:
      - name: name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ProviderName'
          description: Stable provider name.
        description: Stable provider name.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderModelsResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '400':
          description: The configured model provider rejected the request or could not be reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/jobs:
    post:
      tags:
      - jobs
      summary: Create a job
      description: Enqueue extraction for one uploaded file or inline text input.
      operationId: createJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      x-codeSamples:
      - lang: bash
        label: curl
        source: "API=\"${PARSEHAWK_API_URL:-http://127.0.0.1:8000}\"\ncurl --fail --silent --show-error\
          \ \\\n  --request POST \"$API/v1/jobs\" \\\n  --header \"Content-Type: application/json\" \\\
          \n  --data '{\"extractor_name\":\"receipt\",\"file_id\":\"file_...\"}' | jq ."
    get:
      tags:
      - jobs
      summary: List jobs
      description: List extraction jobs, optionally filtered by extractor ID or stable name.
      operationId: listJobs
      parameters:
      - name: extractor_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Only return jobs for this immutable extractor ID.
          title: Extractor Id
        description: Only return jobs for this immutable extractor ID.
      - name: extractor_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Only return jobs for this stable extractor name.
          title: Extractor Name
        description: Only return jobs for this stable extractor name.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobResponse'
                title: Response Listjobs
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/jobs/{job_id}:
    get:
      tags:
      - jobs
      summary: Get a job
      description: Retrieve the current state, result, or failure details for one extraction job.
      operationId: getJob
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable job identifier.
          title: Job Id
        description: Immutable job identifier.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
      - lang: bash
        label: curl
        source: 'API="${PARSEHAWK_API_URL:-http://127.0.0.1:8000}"

          curl --fail --silent --show-error "$API/v1/jobs/job_..." | jq .'
    delete:
      tags:
      - jobs
      summary: Delete a job
      description: Delete a terminal job immediately, or return 202 while cancellation completes for a
        running job.
      operationId: deleteJob
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable job identifier.
          title: Job Id
        description: Immutable job identifier.
      responses:
        '204':
          description: Successful Response
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '202':
          description: Cancellation and deletion accepted.
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/jobs/{job_id}/cancel:
    post:
      tags:
      - jobs
      summary: Cancel a job
      description: Request cancellation and return the resulting job state.
      operationId: cancelJob
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          description: Immutable job identifier.
          title: Job Id
        description: Immutable job identifier.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: The requested ParseHawk resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /v1/schemas/validate:
    post:
      tags:
      - schemas
      summary: Validate an extraction schema
      description: Check a JSON Schema against the ParseHawk authoring dialect and return its canonical
        form plus machine-readable diagnostics.
      operationId: validateSchema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateSchemaRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateSchemaResponse'
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The request or domain input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      externalDocs:
        description: ParseHawk extraction schema dialect
        url: https://docs.parsehawk.com/schemas/parsehawk-extraction-schema.schema.json
components:
  schemas:
    ApiErrorResponse:
      properties:
        detail:
          anyOf:
          - type: string
          - items:
              additionalProperties: true
              type: object
            type: array
          title: Detail
          description: Human-readable error text, or FastAPI validation details when the request does
            not match the declared schema.
      additionalProperties: false
      type: object
      required:
      - detail
      title: ApiErrorResponse
      description: Error returned by request validation or a ParseHawk domain service.
    Body_uploadFile:
      properties:
        upload:
          type: string
          contentMediaType: application/octet-stream
          title: Upload
          description: PDF, image, text, or Markdown document to store for extraction.
      type: object
      required:
      - upload
      title: Body_uploadFile
    ConfigureProviderRequest:
      properties:
        base_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Url
          description: OpenAI-compatible API base URL.
          examples:
          - http://127.0.0.1:11434/v1
        configuration:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Configuration
          description: Provider-specific non-secret settings.
        api_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
          description: API key to store securely. It is never returned by the API.
          writeOnly: true
        api_key_env:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key Env
          description: Environment variable whose current value should be stored as the API key.
          examples:
          - OPENAI_API_KEY
      additionalProperties: false
      type: object
      title: ConfigureProviderRequest
      description: Write-only provider configuration. The API never returns the API key.
    CreateExtractorRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Stable URL-safe extractor name. Generated from display_name when omitted.
          examples:
          - invoice
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Human-readable extractor label. Either this field or name is required.
          examples:
          - Invoice
        instructions:
          type: string
          title: Instructions
          description: Natural-language extraction instructions.
          examples:
          - Extract the invoice header, supplier, and total exactly as shown.
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningEffort'
          - type: 'null'
          description: Optional reasoning effort passed to models that support it.
        provider_name:
          anyOf:
          - $ref: '#/components/schemas/ProviderName'
          - type: 'null'
          description: Configured provider to use. The local OpenAI-compatible provider is the default.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Provider model identifier. Required for hosted providers.
          examples:
          - gpt-4o-mini
        schema:
          additionalProperties: true
          type: object
          title: Schema
          description: JSON Schema that every successful extraction result must satisfy.
        examples:
          items:
            $ref: '#/components/schemas/ExampleRequest'
          type: array
          title: Examples
          description: Optional few-shot examples for difficult document types.
      additionalProperties: false
      type: object
      required:
      - instructions
      - schema
      title: CreateExtractorRequest
      description: Definition used to create a reusable extractor.
    CreateJobRequest:
      properties:
        extractor_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Extractor Id
          description: Immutable extractor identifier. Supply exactly one extractor selector.
          examples:
          - ext_01JZ6QK8M7
        extractor_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Extractor Name
          description: Stable extractor name. Supply exactly one extractor selector.
          examples:
          - invoice
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Uploaded file identifier. Supply exactly one input source.
          examples:
          - file_01JZ6QK8M7
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
          description: Inline text to extract. Supply exactly one input source.
          examples:
          - Invoice INV-1001 from Acme GmbH for EUR 42.00.
      additionalProperties: false
      type: object
      title: CreateJobRequest
      description: Request to enqueue one extraction job.
    ExampleInputKind:
      type: string
      enum:
      - text
      - file
      title: ExampleInputKind
    ExampleInputRequest:
      properties:
        type:
          $ref: '#/components/schemas/ExampleInputKind'
          description: Whether the example input is inline text or a previously uploaded file.
          default: text
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
          description: Inline example text when type is text.
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Uploaded example file identifier when type is file.
      additionalProperties: false
      type: object
      title: ExampleInputRequest
      description: Input used by a few-shot extraction example.
    ExampleRequest:
      properties:
        input:
          anyOf:
          - $ref: '#/components/schemas/ExampleInputRequest'
          - type: string
          title: Input
          description: Representative input for the example.
        output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: string
          title: Output
          description: Expected JSON-compatible extraction output.
      additionalProperties: false
      type: object
      required:
      - input
      - output
      title: ExampleRequest
      description: Few-shot example pairing representative input with expected structured output.
    ExtractorResponse:
      properties:
        id:
          type: string
          title: Id
          description: Immutable extractor identifier.
        name:
          type: string
          title: Name
          description: Stable URL-safe extractor name.
          examples:
          - invoice
        display_name:
          type: string
          title: Display Name
          description: Human-readable extractor label.
        instructions:
          type: string
          title: Instructions
          description: Natural-language extraction instructions.
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningEffort'
          - type: 'null'
          description: Configured reasoning effort.
        provider_name:
          anyOf:
          - $ref: '#/components/schemas/ProviderName'
          - type: 'null'
          description: Configured model provider.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Configured provider model identifier.
        schema:
          additionalProperties: true
          type: object
          title: Schema
          description: Extraction result JSON Schema.
        examples:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Examples
          description: Configured few-shot examples.
        source:
          $ref: '#/components/schemas/ExtractorSource'
          description: How the extractor was created.
        is_prebuilt:
          type: boolean
          title: Is Prebuilt
          description: Whether ParseHawk ships this extractor.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation time.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: UTC last-update time.
      additionalProperties: false
      type: object
      required:
      - id
      - name
      - display_name
      - instructions
      - reasoning_effort
      - provider_name
      - model
      - schema
      - examples
      - source
      - is_prebuilt
      - created_at
      - updated_at
      title: ExtractorResponse
      description: Public representation of a reusable extractor.
    ExtractorSource:
      type: string
      enum:
      - user
      - prebuilt
      title: ExtractorSource
    FileResponse:
      properties:
        id:
          type: string
          title: Id
          description: Immutable file identifier.
          examples:
          - file_01JZ6QK8M7
        file_name:
          type: string
          title: File Name
          description: Original upload filename.
          examples:
          - invoice.pdf
        content_type:
          type: string
          title: Content Type
          description: Detected or supplied media type.
          examples:
          - application/pdf
        size_bytes:
          type: integer
          minimum: 0.0
          title: Size Bytes
          description: Stored file size in bytes.
        sha256:
          type: string
          title: Sha256
          description: Lowercase SHA-256 digest of the stored bytes.
        source:
          $ref: '#/components/schemas/FileSource'
          description: How the file entered ParseHawk.
        is_example:
          type: boolean
          title: Is Example
          description: Whether the file ships as a built-in example.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation time.
      additionalProperties: false
      type: object
      required:
      - id
      - file_name
      - content_type
      - size_bytes
      - sha256
      - source
      - is_example
      - created_at
      title: FileResponse
      description: Metadata for a file stored by ParseHawk.
    FileSource:
      type: string
      enum:
      - user
      - example
      title: FileSource
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthResponse:
      properties:
        status:
          type: string
          const: ok
          title: Status
          description: The API process is ready to accept requests.
      additionalProperties: false
      type: object
      required:
      - status
      title: HealthResponse
      description: Liveness status for the API process.
    JobErrorResponse:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable failure message.
        code:
          type: string
          title: Code
          description: Stable machine-readable failure code.
      additionalProperties: false
      type: object
      required:
      - message
      - code
      title: JobErrorResponse
      description: Terminal extraction error stored with a failed job.
    JobResponse:
      properties:
        id:
          type: string
          title: Id
          description: Immutable job identifier.
          examples:
          - job_01JZ6QK8M7
        extractor_id:
          type: string
          title: Extractor Id
          description: Immutable extractor identifier used by the job.
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Input file identifier for file-based jobs.
        source_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Text
          description: Inline source text for text-based jobs.
        provider_name_used:
          anyOf:
          - $ref: '#/components/schemas/ProviderName'
          - type: 'null'
          description: Provider selected when execution starts.
        model_used:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Used
          description: Model selected when execution starts.
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current job lifecycle state.
        result:
          anyOf:
          - $ref: '#/components/schemas/JobResultResponse'
          - type: 'null'
          description: Validated result for completed jobs.
        error:
          anyOf:
          - $ref: '#/components/schemas/JobErrorResponse'
          - type: 'null'
          description: Failure details for failed jobs.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation time.
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: UTC execution start time.
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: UTC terminal-state time.
      additionalProperties: false
      type: object
      required:
      - id
      - extractor_id
      - file_id
      - source_text
      - provider_name_used
      - model_used
      - status
      - result
      - error
      - created_at
      - started_at
      - completed_at
      title: JobResponse
      description: Current state and eventual result of one extraction job.
    JobResultResponse:
      properties:
        data:
          additionalProperties: true
          type: object
          title: Data
          description: Result validated against the extractor schema.
      additionalProperties: false
      type: object
      required:
      - data
      title: JobResultResponse
      description: Validated structured output produced by an extraction job.
    JobStatus:
      type: string
      enum:
      - queued
      - running
      - completed
      - failed
      - canceling
      - deleting
      - canceled
      title: JobStatus
    ProviderModelsResponse:
      properties:
        models:
          items:
            type: string
          type: array
          title: Models
          description: Provider model identifiers.
      additionalProperties: false
      type: object
      required:
      - models
      title: ProviderModelsResponse
      description: Models currently advertised by a configured provider.
    ProviderName:
      type: string
      enum:
      - openai
      - microsoft_foundry
      - openai_compatible_api
      title: ProviderName
      description: 'The fixed set of model providers ParseHawk ships.


        Providers are preconfigured and configurable, not user-creatable, so the

        name doubles as the stable identifier extractors reference and as the

        discriminator the engine factory switches on.'
    ProviderResponse:
      properties:
        name:
          $ref: '#/components/schemas/ProviderName'
          description: Stable provider name.
        base_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Url
          description: OpenAI-compatible API base URL when applicable.
        configuration:
          additionalProperties: true
          type: object
          title: Configuration
          description: Provider-specific non-secret settings.
        has_api_key:
          type: boolean
          title: Has Api Key
          description: Whether ParseHawk has a stored API key for the provider.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: UTC creation time.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: UTC last-update time.
      additionalProperties: false
      type: object
      required:
      - name
      - base_url
      - configuration
      - has_api_key
      - created_at
      - updated_at
      title: ProviderResponse
      description: Non-secret configuration for one model provider.
    ReasoningEffort:
      type: string
      enum:
      - none
      - minimal
      - low
      - medium
      - high
      - xhigh
      title: ReasoningEffort
      description: 'Explicit reasoning effort for an extractor''s model.


        The values mirror OpenAI''s ``reasoning_effort`` parameter. Extractors store

        ``None`` by default, which means "send no reasoning parameter and use the

        model''s own default" — the only setting that is safe for every model.

        Which explicit values a model accepts is the provider''s call; incompatible

        pairs surface the provider''s error at extraction time.'
    RootResponse:
      properties:
        message:
          type: string
          title: Message
          description: Short API welcome message with a link to the documentation.
      additionalProperties: false
      type: object
      required:
      - message
      title: RootResponse
      description: API welcome message.
    SchemaDiagnostic:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable diagnostic message.
        path:
          type: string
          title: Path
          description: JSONPath-like location in the submitted schema.
          default: $
        code:
          type: string
          title: Code
          description: Stable diagnostic code.
          examples:
          - unsupported_keyword
      additionalProperties: false
      type: object
      required:
      - message
      - code
      title: SchemaDiagnostic
      description: One machine-readable schema validation diagnostic.
    UpdateExtractorRequest:
      properties:
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: New human-readable label.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: New extraction instructions.
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningEffort'
          - type: 'null'
          description: New reasoning effort; explicit null restores the model default.
        provider_name:
          anyOf:
          - $ref: '#/components/schemas/ProviderName'
          - type: 'null'
          description: New provider selection.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: New model selection; explicit null uses the local provider default.
        schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Schema
          description: Replacement extraction schema.
        examples:
          anyOf:
          - items:
              $ref: '#/components/schemas/ExampleRequest'
            type: array
          - type: 'null'
          title: Examples
          description: Replacement few-shot example set.
      additionalProperties: false
      type: object
      title: UpdateExtractorRequest
      description: Partial update for an existing extractor.
    UpsertExtractorRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Optional body name. When supplied it must match the path reference.
        display_name:
          type: string
          title: Display Name
          description: Human-readable extractor label.
          examples:
          - Invoice
        instructions:
          type: string
          title: Instructions
          description: Natural-language extraction instructions.
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningEffort'
          - type: 'null'
          description: Optional reasoning effort passed to models that support it.
        provider_name:
          anyOf:
          - $ref: '#/components/schemas/ProviderName'
          - type: 'null'
          description: Configured provider to use.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Provider model identifier.
        schema:
          additionalProperties: true
          type: object
          title: Schema
          description: JSON Schema that every successful extraction result must satisfy.
        examples:
          items:
            $ref: '#/components/schemas/ExampleRequest'
          type: array
          title: Examples
          description: Optional few-shot examples.
      additionalProperties: false
      type: object
      required:
      - display_name
      - instructions
      - schema
      title: UpsertExtractorRequest
      description: Complete extractor definition used to create or replace an extractor by reference.
    ValidateSchemaRequest:
      properties:
        schema:
          additionalProperties: true
          type: object
          title: Schema
          description: ParseHawk extraction schema. This is the public authoring dialect documented in
            docs/schemas/parsehawk-extraction-schema.schema.json.
          examples:
          - additionalProperties: false
            properties:
              invoice_number:
                type:
                - string
                - 'null'
                x-parsehawk:
                  semantic: verbatim-string
              total:
                type: number
              currency:
                type: string
                x-parsehawk:
                  semantic: currency
            required:
            - invoice_number
            - total
            - currency
            type: object
      additionalProperties: false
      type: object
      required:
      - schema
      title: ValidateSchemaRequest
      description: Request to validate a ParseHawk extraction schema.
    ValidateSchemaResponse:
      properties:
        valid:
          type: boolean
          title: Valid
          description: Whether the schema is accepted by ParseHawk.
        schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Schema
          description: Canonical ParseHawk extraction schema when validation succeeds.
        warnings:
          items:
            $ref: '#/components/schemas/SchemaDiagnostic'
          type: array
          title: Warnings
          description: Non-blocking diagnostics.
        errors:
          items:
            $ref: '#/components/schemas/SchemaDiagnostic'
          type: array
          title: Errors
          description: Blocking diagnostics that make the schema invalid.
      additionalProperties: false
      type: object
      required:
      - valid
      title: ValidateSchemaResponse
      description: Validation result and canonical schema when accepted.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
tags:
- name: health
  description: API discovery and process liveness.
- name: files
  description: Upload documents once, inspect their metadata, and reuse them across jobs.
- name: schemas
  description: Validate extraction schemas before attaching them to extractors.
- name: extractors
  description: Reusable extraction instructions, schemas, examples, provider, and model choices.
- name: providers
  description: Configure local or hosted model providers without exposing stored secrets.
- name: jobs
  description: Create, inspect, cancel, and delete asynchronous extraction jobs.
security: []