openapi: 3.1.0
info:
  title: Sensible REST API
  description: >-
    REST API for document understanding: extract, classify, fill, generate, and
    manage document types, configs, reference documents, and extractions.
    Authenticated with a bearer token (API key).
  version: "0"
  contact:
    name: Sensible
    url: https://docs.sensible.so/
servers:
  - url: https://api.sensible.so/v0
    description: Sensible production API
security:
  - bearerAuth: []
tags:
  - name: Extract
    description: Document data extraction
  - name: Classify
    description: Document type classification
  - name: Document Types
    description: Manage document types
  - name: Configs
    description: Manage document type configs (SenseML)
  - name: Reference Documents
    description: Manage reference documents per type
  - name: Documents
    description: Retrieve documents and extractions
  - name: Upload
    description: Generate upload URLs for documents
  - name: Account
    description: Account-related resources
paths:
  /extract/{document_type}:
    post:
      tags: [Extract]
      summary: Extract data from a document (default config)
      operationId: extractDocument
      parameters:
        - $ref: '#/components/parameters/DocumentType'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExtractRequest' }
      responses:
        '200': { $ref: '#/components/responses/ExtractResponse' }
  /extract/{document_type}/{config_name}:
    post:
      tags: [Extract]
      summary: Extract data from a document using a specific config
      operationId: extractDocumentWithConfig
      parameters:
        - $ref: '#/components/parameters/DocumentType'
        - $ref: '#/components/parameters/ConfigName'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExtractRequest' }
      responses:
        '200': { $ref: '#/components/responses/ExtractResponse' }
  /extract_from_url/{document_type}:
    post:
      tags: [Extract]
      summary: Extract from a URL-hosted document (default config)
      operationId: extractFromUrl
      parameters:
        - $ref: '#/components/parameters/DocumentType'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExtractFromUrlRequest' }
      responses:
        '200': { $ref: '#/components/responses/ExtractResponse' }
  /extract_from_url/{document_type}/{config_name}:
    post:
      tags: [Extract]
      summary: Extract from a URL-hosted document using a specific config
      operationId: extractFromUrlWithConfig
      parameters:
        - $ref: '#/components/parameters/DocumentType'
        - $ref: '#/components/parameters/ConfigName'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ExtractFromUrlRequest' }
      responses:
        '200': { $ref: '#/components/responses/ExtractResponse' }
  /classify_document:
    post:
      tags: [Classify]
      summary: Submit a document for asynchronous classification
      operationId: classifyDocument
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ClassifyRequest' }
      responses:
        '200': { description: Classification job accepted }
  /classify_document_sync:
    post:
      tags: [Classify]
      summary: Synchronously classify a document
      operationId: classifyDocumentSync
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ClassifyRequest' }
      responses:
        '200': { description: Classification result }
  /document_types:
    get:
      tags: [Document Types]
      summary: List document types
      operationId: listDocumentTypes
      responses:
        '200': { description: Array of document types }
    post:
      tags: [Document Types]
      summary: Create a document type
      operationId: createDocumentType
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
      responses:
        '201': { description: Created document type }
  /document_types/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Document Types]
      summary: Retrieve a document type
      operationId: getDocumentType
      responses: { '200': { description: Document type } }
    put:
      tags: [Document Types]
      summary: Update a document type
      operationId: updateDocumentType
      responses: { '200': { description: Updated } }
    delete:
      tags: [Document Types]
      summary: Delete a document type
      operationId: deleteDocumentType
      responses: { '204': { description: Deleted } }
  /document_types/{type_id}/configs:
    parameters:
      - $ref: '#/components/parameters/TypeId'
    get:
      tags: [Configs]
      summary: List configs for a document type
      operationId: listConfigs
      responses: { '200': { description: Array of configs } }
    post:
      tags: [Configs]
      summary: Create a config for a document type
      operationId: createConfig
      responses: { '201': { description: Created config } }
  /document_types/{type_id}/configs/{name}:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - $ref: '#/components/parameters/ConfigNamePath'
    get:
      tags: [Configs]
      summary: Retrieve a config
      operationId: getConfig
      responses: { '200': { description: Config } }
    put:
      tags: [Configs]
      summary: Update a config
      operationId: updateConfig
      responses: { '200': { description: Updated } }
    delete:
      tags: [Configs]
      summary: Delete a config
      operationId: deleteConfig
      responses: { '204': { description: Deleted } }
  /document_types/{type_id}/configs/{name}/versions:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - $ref: '#/components/parameters/ConfigNamePath'
    get:
      tags: [Configs]
      summary: List versions of a config
      operationId: listConfigVersions
      responses: { '200': { description: Array of versions } }
  /document_types/{type_id}/configs/{name}/versions/{version}:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - $ref: '#/components/parameters/ConfigNamePath'
      - in: path
        name: version
        required: true
        schema: { type: string }
    get:
      tags: [Configs]
      summary: Retrieve a specific config version
      operationId: getConfigVersion
      responses: { '200': { description: Config version } }
    delete:
      tags: [Configs]
      summary: Delete a specific config version
      operationId: deleteConfigVersion
      responses: { '204': { description: Deleted } }
  /document_types/{type_id}/configs/{name}/versions/{version}/publish:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - $ref: '#/components/parameters/ConfigNamePath'
      - in: path
        name: version
        required: true
        schema: { type: string }
    put:
      tags: [Configs]
      summary: Publish a config version
      operationId: publishConfigVersion
      responses: { '200': { description: Published } }
  /document_types/{type_id}/reference_documents:
    parameters:
      - $ref: '#/components/parameters/TypeId'
    get:
      tags: [Reference Documents]
      summary: List reference documents for a document type
      operationId: listReferenceDocuments
      responses: { '200': { description: Array of reference documents } }
    post:
      tags: [Reference Documents]
      summary: Create a reference document
      operationId: createReferenceDocument
      responses: { '201': { description: Created reference document } }
  /document_types/{type_id}/reference_documents/{id}:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Reference Documents]
      summary: Retrieve a reference document
      operationId: getReferenceDocument
      responses: { '200': { description: Reference document } }
    put:
      tags: [Reference Documents]
      summary: Update a reference document
      operationId: updateReferenceDocument
      responses: { '200': { description: Updated } }
    delete:
      tags: [Reference Documents]
      summary: Delete a reference document
      operationId: deleteReferenceDocument
      responses: { '204': { description: Deleted } }
  /document_types/{type_id}/reference_documents/{id}/extract_all_text:
    parameters:
      - $ref: '#/components/parameters/TypeId'
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Reference Documents]
      summary: Extract all text from a reference document
      operationId: extractAllTextReferenceDocument
      responses: { '200': { description: Extracted text } }
  /generate_upload_url/{document_type}:
    post:
      tags: [Upload]
      summary: Generate an upload URL for a document
      operationId: generateUploadUrl
      parameters:
        - $ref: '#/components/parameters/DocumentType'
      responses: { '200': { description: Upload URL response } }
  /generate_upload_url/{document_type}/{config_name}:
    post:
      tags: [Upload]
      summary: Generate an upload URL for a document with a specific config
      operationId: generateUploadUrlWithConfig
      parameters:
        - $ref: '#/components/parameters/DocumentType'
        - $ref: '#/components/parameters/ConfigName'
      responses: { '200': { description: Upload URL response } }
  /documents:
    get:
      tags: [Documents]
      summary: List documents
      operationId: listDocuments
      responses: { '200': { description: Array of documents } }
  /documents/{id}:
    get:
      tags: [Documents]
      summary: Retrieve a document
      operationId: getDocument
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses: { '200': { description: Document } }
  /extractions/{id}:
    put:
      tags: [Documents]
      summary: Update an extraction
      operationId: updateExtraction
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses: { '200': { description: Updated extraction } }
  /account/auth_tokens:
    get:
      tags: [Account]
      summary: List account auth tokens
      operationId: listAuthTokens
      responses: { '200': { description: Array of tokens } }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  parameters:
    DocumentType:
      in: path
      name: document_type
      required: true
      schema: { type: string }
      description: Document type identifier
    ConfigName:
      in: path
      name: config_name
      required: true
      schema: { type: string }
      description: Config name
    ConfigNamePath:
      in: path
      name: name
      required: true
      schema: { type: string }
      description: Config name
    TypeId:
      in: path
      name: type_id
      required: true
      schema: { type: string }
      description: Document type ID
  schemas:
    ExtractRequest:
      type: object
      properties:
        document_url: { type: string, format: uri }
        environment: { type: string, enum: [production, development] }
    ExtractFromUrlRequest:
      type: object
      properties:
        document_url: { type: string, format: uri }
        document_name: { type: string }
        environment: { type: string, enum: [production, development] }
    ClassifyRequest:
      type: object
      properties:
        document_url: { type: string, format: uri }
        types:
          type: array
          items: { type: string }
  responses:
    ExtractResponse:
      description: Extraction response
      content:
        application/json:
          schema:
            type: object
            properties:
              id: { type: string }
              status: { type: string }
              parsed_document: { type: object }