openapi: 3.0.3
info:
  title: Sensible Classification API
  version: v0
  description: Classify a document into one of the document types defined in your Sensible account, synchronously or asynchronously.
    Use classification to route documents in a workflow or label documents in a system of record.
  contact:
    name: Sensible
    url: https://www.sensible.so
    email: support@sensible.so
  license:
    name: Proprietary
    url: https://www.sensible.so/terms
servers:
- url: https://api.sensible.so/v0
  description: Production server
security:
- bearerAuth: []
tags:
- name: Document
  description: Classify documents by type
paths:
  /classify:
    post:
      operationId: classify-document-sync
      summary: Classify document by type (sync)
      description: "\n**Note:** Use this Classify endpoint for testing. Use the asynchronous Classify endpoint for production.\n\
        \nClassify a document into one of the document types you defined in your Sensible account. For more information, see\
        \ [Classifying documents by type](https://docs.sensible.so/docs/classify).\n\nUse this endpoint:\n\n - In an extraction\
        \ workflow. For example, determine which documents to extract prior to calling a Sensible extraction endpoint.\n -\
        \ Outside an extraction workflow. For example, determine where to route each document or to label each document in\
        \ a system of record.\n\nTo post the document bytes, specify the non-encoded document bytes as the entire request\
        \ body,and specify the `Content-Type` header, for example,\"application/pdf\" or \"image/jpeg\".\n\nFor supported\
        \ file size and types, see [Supported file types](https://docs.sensible.so/docs/file-types).\n    \n"
      parameters:
      - $ref: '#/components/parameters/document_types'
      requestBody:
        $ref: '#/components/requestBodies/SupportedFileTypes'
      tags:
      - Document
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifySingleResponse'
          description: 'The document type in your Sensible account that''s most similar to this document.

            '
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /classify/async:
    post:
      operationId: classify-document
      summary: Classify document by type
      description: "Classify a document into one of the document types you defined in your Sensible account. For more information,\
        \ see [Classifying documents by type](https://docs.sensible.so/docs/classify).\nTo retrieve document's classification,\
        \ poll the `download_link` in this endpoint's response until it returns a non-error response.\n\nUse this endpoint:\n\
        \n - In an extraction workflow. For example, determine which documents to extract prior to calling a Sensible extraction\
        \ endpoint.\n - Outside an extraction workflow. For example, determine where to route each document or to label each\
        \ document in a system of record.\n\nTo post the document bytes, specify the non-encoded document bytes as the entire\
        \ request body,and specify the `Content-Type` header, for example,\"application/pdf\" or \"image/jpeg\".\n\nFor supported\
        \ file size and types, see [Supported file types](https://docs.sensible.so/docs/file-types).\n"
      parameters:
      - $ref: '#/components/parameters/document_types'
      requestBody:
        $ref: '#/components/requestBodies/SupportedFileTypes'
      tags:
      - Document
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyAsyncSingleResponse'
          description: 'Download link for the classification response. Poll the link until it returns a non-error response.

            '
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token using a Sensible API key. Create keys at https://app.sensible.so/account/.
  schemas:
    ClassifySingleResponse:
      type: object
      properties:
        document_type:
          type: object
          description: The document type defined in your Sensible account that this document is most similar to.
          properties:
            id:
              type: string
              description: Unique ID for the document type.
            name:
              type: string
              description: User-friendly name for the document type.
            score:
              type: number
              description: Deprecated. Similarity score comparing the document to the document type, where a score of 1 indicates
                a match.
        reference_documents:
          type: object
          description: Deprecated. Empty array. Scoring for embeddings-based classification, replaced by LLM-based classification.
          additionalProperties: true
        classification_summary:
          type: object
          additionalProperties: true
          description: "Deprecated. Empty array. Scoring for embeddings-based classification, replaced by LLM-based classification.\
            \ \n"
      example:
        document_type:
          id: 77c2ab88-3389-4ea8-93c7-912c2bfd373a
          name: 1040s
          score: 1
        reference_documents: []
        classification_summary: []
    ClassifyAsyncSingleResponse:
      type: object
      properties:
        id:
          type: string
          description: ID for this classification response.
        content_type:
          type: string
          description: File format of the document for which you requested classification.
        download_link:
          description: 'Poll until the download URL returns a non-error response. Links to a JSON download that contains the
            same response as from the synchronous Classify endpoint request.

            '
          type: string
          format: url
      example:
        id: 49f844ba-4429-4974-919d-2f1bdfa95f7c
        content_type: application/pdf
        download_link: https://sensible-so-document-type-bucket-dev-us-west-2.s3.us-west-2.amazonaws.com/c024cd1c-5f33-4a82-b2ea-2c807e44988b/CLASSIFICATION/49f844ba-4429-4974-919d-2f1bdfa95f7c.json?AWSAccessKeyId=REST_REDACTED
  parameters:
    document_types:
      name: document_types
      in: query
      description: Comma-delimited list of document types Sensible uses to classify the document.  If you don't specify this,
        Sensible uses all the document types you define in your account.
      schema:
        type: array
        items:
          type: string
      example: 1040s, pay_stubs, bank_statements
  requestBodies:
    SupportedFileTypes:
      description: Supported [file types](https://docs.sensible.so/docs/file-types).
      required: true
      content:
        application/pdf:
          schema:
            type: string
            format: binary
            description: non-encoded document bytes as the entire request body
        image/jpeg:
          schema:
            type: string
            format: binary
        image/png:
          schema:
            type: string
            format: binary
        image/tiff:
          schema:
            type: string
            format: binary
        application/vnd.openxmlformats-officedocument.wordprocessingml.document:
          schema:
            type: string
            format: binary
            description: non-encoded document bytes as the entire request body
        application/msword:
          schema:
            type: string
            format: binary
            description: non-encoded document bytes as the entire request body
        application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
          schema:
            type: string
            format: binary
            description: non-encoded document bytes as the entire request body
        text/csv:
          schema:
            type: string
            format: binary
            description: non-encoded document bytes as the entire request body
  responses:
    '400':
      description: Bad Request
      content:
        text/plain:
          schema:
            title: Bad Request
            type: string
            example: Messages related to the file content type, to reading or OCRing the file, or to classifying the document.
    '401':
      description: Not authorized
      content:
        text/plain:
          schema:
            title: Unauthorized
            type: string
            example: Unauthorized
    '415':
      description: Unsupported Media Type
      content:
        text/plain:
          schema:
            title: Unsupported Media Type
            type: string
            example: Messages related to the file format of the document.
    '429':
      description: Too Many Requests
      content:
        text/plain:
          schema:
            title: Unsupported Media Type
            type: string
            example: One of the following error messages - Attempt limit exceeded, please retry after some time. Free accounts
              are limited to 150 API calls per month. Please upgrade your account to make additional calls. Pro accounts are
              limited to 5,000 API calls per month. Please upgrade your account to make additional calls.
    '500':
      description: Internal Server Error
      content:
        text/plain:
          schema:
            title: Sensible encountered an unknown error
            type: string
            example: Sensible encountered an unknown error