openapi.yml

openapi: 3.0.3
servers:
  - url: https://api.sensible.so/v0
    description: Production server (uses live data)
info:
  title: Configuration
  version: 0.0.1
  description: Sensible API for configuring document types, SenseML configurations, and reference documents.
  license: # TODO: fill in
    name: Sensible API
    url: https://www.TBD.org/licenses/LICENSE-2.0.html
paths:

  /document_types:
    get:
      operationId: list-document-types
      summary: List document types for this account
      description: List all document types for this account.
      tags:
      - Document type
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllDocumentTypes'
          description: List of document types for the current account
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    post:
      operationId: create-document-type
      summary: Create document type
      description: Create a document type.
      tags:
      - Document type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDocumentType'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentType'
          description: List of document types for the current account
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
    get:
      operationId: get-document-type
      summary: Get document type
      description: Find the document type id using the `/document_types` endpoint.
      tags:
      - Document type
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentType'
          description: Identified document type
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    put:
      operationId: update-document-type
      summary: Update document type
      description: |
        Update an existing document type with new information. For example, use this endpoint to add validations:

        ```curl
        curl --location --request PUT 'https://api.sensible.so/v0/document_types/<TYPE_ID>' \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data-raw '{"schema":{"validations":[{"description":"example validation to test broker email format","condition":{"match":[{"var":"broker\\.email.value"},"^\\S+\\@\\S+$"]},"severity":"warning","fields":["test"]}]}} '
        ```


      tags:
      - Document type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutDocumentType'
            example:
              name: pay_stubs
              schema:
                validations:
                  - description: total pay is listed in paystub
                    condition: {"exists":[{"var":"total_pay.value"}]}
                    severity: warning

      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentType'
          description: Identified document type
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    delete:
      operationId: delete-document-type
      summary: Delete document type
      description: |
        Delete a document type and everything it contains, for example configurations and reference PDfs,
        but not its extraction history displayed in the Sensible app.
      tags:
      - Document type
      responses:
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/configurations:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
    get:
      operationId: list-configurations
      summary: List configurations in a document type
      description: List configurations in a document type.
      tags:
      - Configuration
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllConfigurations'
          description: List of document types for the current account
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    post:
      operationId: create-configuration
      summary: Create configuration in a document type
      description: Pass the configuration as stringified JSON.
      tags:
      - Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostConfiguration'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
          description: The created configuration
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/configurations/{config-name}:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
      - $ref: '#/components/parameters/configurationName'
    get:
      operationId: get-configuration
      summary: Get configuration
      description: Get a configuration as stringified JSON.
      tags:
      - Configuration
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
          description: The identified configuration
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    put:
      operationId: update-configuration
      summary: Update configuration
      description: Replace a published or draft version of the configuration.
      tags:
      - Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutConfiguration'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
          description: The created configuration
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    delete:
      operationId: delete-configuration
      summary: Delete configuration
      description: Delete a configuration and its versions.
      tags:
      - Configuration
      responses:
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/configurations/{config-name}/versions:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
      - $ref: '#/components/parameters/configurationName'
    get:
      operationId: get-configuration-versions
      summary: List versions for a configuration
      description: Get the version ids for a configuration.
      tags:
      - Configuration
      responses:
        200:
          description: Version information for the identified configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationVersionsResponse'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/configurations/{config-name}/{version}:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
      - $ref: '#/components/parameters/configurationName'
      - $ref: '#/components/parameters/versionIdentifier'
    get:
      operationId: get-configuration-by-version
      summary: Get configuration by version
      description: Get a configuration as stringified JSON by version id.
      tags:
      - Configuration
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
          description: The identified configuration
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    put:
      operationId: publish-configuration-by-version
      summary: Publish configuration to an environment
      description: To publish to an environment instead of as the current draft, the configuration must be valid according to this [schema](https://schema.sensible.so/configuration.schema.json).
      tags:
      - Configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishConfigurationVersion'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
          description: The identified configuration
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    delete:
      operationId: delete-configuration-by-version
      summary: Delete draft or unpublish configuration
      description: >-
        To delete a draft, specify a version name in the `version` parameter.
        To unpublish a configuration, enter the publication environment name in the `version` parameter, for example,
        `development`.

      tags:
      - Configuration
      parameters:
        - $ref: '#/components/parameters/documentTypeId'
        - $ref: '#/components/parameters/configurationName'
        - in: path
          name: version
          required: true
          description: >-
            if unpublishing a configuration from an environment, the name of the environment (`development`, `production`.)
            If deleting the current draft, the version number of the current draft.
          schema:
            type: string
      responses:
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'

  /document_types/{type-id}/goldens:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
    get:
      operationId: list-reference-documents
      summary: List all reference documents in a document type
      description: List all reference documents in a document type
      tags:
      - Reference document
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllGoldens'
          description: List of reference documents for the current account
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    post:
      operationId: create-reference-document
      summary: Create reference document
      description: >-
        Specify document metadata in the request, and get back an `upload_url` at which to put the PDF,
        for example with `curl -T ./sample.pdf`.
      tags:
      - Reference document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostGolden'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoldenResponse'
          description: The created reference document
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/goldens/{document-name}:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
      - $ref: '#/components/parameters/documentName'
    get:
      operationId: get-reference-document
      summary: Get reference document metadata
      description: Get download URL and other metadata for a reference document.
      tags:
      - Reference document
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoldenResponse'
          description: The identified reference document
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    put:
      operationId: update-reference-document
      summary: Update metadata for a reference document
      description: Update metadata for a reference document
      tags:
      - Reference document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutGolden'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoldenResponse'
          description: The updated reference document
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
    delete:
      operationId: delete-reference-document
      summary: Delete reference document
      description: Delete a reference document and break associations to any configs.
      tags:
      - Reference document
      responses:
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'
  /document_types/{type-id}/goldens/{document-name}/configuration:
    parameters:
      - $ref: '#/components/parameters/documentTypeId'
      - $ref: '#/components/parameters/documentName'
    delete:
      operationId: delete-reference-document-association
      summary: Unassociate reference document from configuration
      description: Break the association between a reference document and its configuration.
      tags:
      - Reference document
      responses:
        204:
          $ref: '#/components/responses/204'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'

  # Comment: decision to remove from public API reference as of march 2023; not being used. if make public, check accuracy of response model

  # /extract_from_golden/{type-name}:
  #   parameters:
  #     - $ref: '#/components/parameters/documentTypeName'
  #     - $ref: '#/components/parameters/environment'
  #   post:
  #     operationId: extract-from-reference-document
  #     summary: Extract from reference document
  #     description: >-
  #       Extract from a specified reference document in a document type.
  #       Return the best-scoring extraction from the configurations in the document type, or from the
  #       specified configuration.
  #     tags:
  #     - Reference document extraction
  #     requestBody:
  #       required: true
  #       content:
  #         application/json:
  #           schema:
  #             $ref: '#/components/schemas/PostGoldenExtraction'
  #     responses:
  #         '200':
  #           content:
  #             application/json:
  #               schema:
  #                 $ref: '#/components/schemas/ResponseGoldenExtraction'
  #           description: The structured data extracted from the reference document

  #         400: # todo I didn't verify 40x responses for any extract_from_goldens, just assumed
  #           $ref: '#/components/responses/400'
  #         401:
  #           $ref: '#/components/responses/401'
  #         404:
  #           $ref: '#/components/responses/404'
  #         415:
  #           $ref: '#/components/responses/415'
  #         500:
  #           $ref: '#/components/responses/500'

  # /extract_from_golden/{type-name}/{config-name}:
  #   parameters:
  #     - $ref: '#/components/parameters/documentTypeName'
  #     - $ref: '#/components/parameters/configurationName'
  #     - $ref: '#/components/parameters/environment'
  #   post:
  #     operationId: extract-from-reference-document-and-config
  #     summary: Extract from reference document using configuration
  #     description: Extract from a reference document using the specified published configuration
  #     tags:
  #     - Reference document extraction
  #     requestBody:
  #       required: true
  #       content:
  #         application/json:
  #           schema:
  #             $ref: '#/components/schemas/PostGoldenExtraction'
  #     responses:
  #         '200':
  #           content:
  #             application/json:
  #               schema:
  #                 $ref: '#/components/schemas/ResponseGoldenExtraction'
  #           description: The structured data extracted from the reference document

  #         400:
  #           $ref: '#/components/responses/400'
  #         401:
  #           $ref: '#/components/responses/401'
  #         404:
  #           $ref: '#/components/responses/404'
  #         415:
  #           $ref: '#/components/responses/415'
  #         500:
  #           $ref: '#/components/responses/500'

  # /extract_from_golden/{type-name}/{config-name}/{version}/{document-name}:
  #   parameters:
  #     - $ref: '#/components/parameters/documentTypeName'
  #     - $ref: '#/components/parameters/configurationName'
  #     - $ref: '#/components/parameters/versionIdentifier'
  #     - $ref: '#/components/parameters/documentName'
  #     - $ref: '#/components/parameters/environment'
  #   get:
  #     operationId: extract-from-reference-document-and-config-version
  #     summary: Extract from reference document using configuration version
  #     description: Extract from a reference document using the specified version of a configuration.
  #     tags:
  #     - Reference document extraction
  #     responses:
  #         '200':
  #           content:
  #             application/json:
  #               schema:
  #                 $ref: '#/components/schemas/ResponseGoldenExtraction'
  #           description: The structured data extracted from the reference document
  #         400:
  #           $ref: '#/components/responses/400'
  #         401:
  #           $ref: '#/components/responses/401'
  #         404:
  #           $ref: '#/components/responses/404'
  #         415:
  #           $ref: '#/components/responses/415'
  #         500:
  #           $ref: '#/components/responses/500'

  /extract_text_from_golden/{type-name}:
    parameters:
      - $ref: '#/components/parameters/documentTypeName'
      # - $ref: '#/components/parameters/environment' # note: not documenting the env parameter that, while in the handler, is ignored for this endpoint
    post:
      operationId: extract-all-text-from-reference-document
      summary: Extract all text from reference document
      description: >-
        Get all the text (lines) for a reference document as standardized output. The output is an array of pages with metadata such as text positioning.
        If you specify a configuration, Sensible uses preprocessors defined in the configuration to process the text.
      tags:
      - Reference document
      requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostGoldenExtraction'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseStandardText'
          description: All the text in the document
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        415:
          $ref: '#/components/responses/415'
        500:
          $ref: '#/components/responses/500'

components:
  parameters:
    documentTypeId:
      name: type-id
      required: true
      in: path
      description: The unique document type identifier in v4 UUID format. Find IDs using the `/document_types` endpoint.
      schema:
        $ref: '#/components/schemas/UniqueId'
    documentTypeName:
      name: type-name
      required: true
      in: path
      description: User-friendly name for a document type
      schema:
        $ref: '#/components/schemas/DocumentTypeName'
    configurationName:
      name: config-name
      required: true
      in: path
      description: Unique name for a configuration. Find it in the Sensible app or from the `/document_types/{type-id}/configurations` endpoint.
      example: anyco_auto_insurance_quote
      schema:
        $ref: '#/components/schemas/Name'
    documentName:
      name: document-name
      required: true
      in: path
      description: Unique name for a document. Find it in the Sensible app or from the `/document_types/{type-id}}/goldens` endpoint.
      example: best_scan_form_no_1234
      schema:
        $ref: '#/components/schemas/Name'


    versionIdentifier:
      name: version
      required: true
      in: path
      description: Unique identifier for a configuration version.
      schema:
        type: string
    environment:
      name: environment
      in: query
      description: >-
        If you specify `development`, extracts preferentially using config versions
        published to the development environment in the Sensible app. The extraction runs all configs in the doc type before
        picking the best fit. For each config, falls back to production version if no development version of the config exists.
      schema:
        type: string
        enum: [production, development]
        default: production
  schemas:
    UniqueId:
      type: string
      format: uuid
      description: Unique identifier
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    Name: #used for params
      type: string
      pattern: ^[a-z0-9_]*$
      minLength: 3
      maxLength: 128
      description: User-friendly name
    DocumentTypeName:
      description: Unique user-friendly name for a document type
      example: auto_insurance_quotes_all_carriers
      type: string
    ConfigurationName:
      description: Unique user-friendly name for a configuration
      example: anyco_auto_insurance_quote
      type: string
    DocumentName:
      description: Unique user-friendly name for a document
      example: best_scan_form_num_1234
      type: string
    Date:
      type: string
      format: date-time
      description: ISO 8601 date-time.
    DocumentType:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/DocumentTypeName'
        id:
          $ref: '#/components/schemas/UniqueId'
        created:
          $ref: '#/components/schemas/Date'
        schema:
          $ref: '#/components/schemas/DocumentTypeOutput'
      required:
        - name
        - id
        - created
        - schema
      additionalProperties: false
    GetAllDocumentTypes:
      type: array
      items:
        type: object
        properties:
          name:
            $ref: '#/components/schemas/DocumentTypeName'
          id:
            $ref: '#/components/schemas/UniqueId'
          created:
            $ref: '#/components/schemas/Date'
          schema:
            $ref: '#/components/schemas/DocumentTypeOutput'
        required:
          - name
          - id
          #- created
        additionalProperties: false
    PostDocumentType:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/DocumentTypeName'
        schema:
          $ref: '#/components/schemas/DocumentTypeOutput'
      required:
        - name
        - schema
      additionalProperties: false

    DocumentTypeOutput:
      type: object
      additionalProperties: false
      properties:
        fingerprint_mode:
          enum:
            - fallback_to_all
            - strict
          type: string
          description: The Sensible app defaults to `fallback_to_all`.

        ocr_engine:
          enum:
            - microsoft
            - amazon
            - google
            - lazarus
          type: string
          description: |
            For information about each OCR engine, see [OCR engine](/senseml-reference/document-type-settings/ocr-engine).

        prevent_default_merge_lines:
          type: boolean
          description: |
            Prevents the built-in line merging that occurs before  the
            [Merge Lines](/senseml-reference/preprocessors/merge-lines) preprocessor.

        ocr_level:
          enum:
            - 0
            - 2
            - 4
            - 5
          type: number
          description: |
            See [OCR level](/senseml-reference/document-type-settings/ocr-level).
        validations:
          description: Array of validations. See https://docs.sensible.so/docs/validate-extractions
          items:
            $ref: "#/components/schemas/ValidationRequest"
          type: array


    PutDocumentType:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
        schema:
          $ref: '#/components/schemas/DocumentTypeOutput'
      additionalProperties: false


    GetAllGoldens:
      type: array
      items:
        $ref: '#/components/schemas/GoldenResponse'
    GoldenResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/DocumentName'
        created:
          $ref: '#/components/schemas/Date'
        configuration:
          $ref: '#/components/schemas/AssociatedConfigurationName'
        error:
          type: string
          description: Any errors that occurred processing the reference document
        upload_url:
          type: string
          description: If present, the URL to which a reference document can be PUT
        download_url:
          type: string
          description: If present, the URL to GET to retrieve the reference document
        thumbnail_url:
          type: string
          description: If present, the URL to GET to retrieve a thumbnail image of the first page of the reference document
      required:
        - name
        - created
      additionalProperties: false
    PostGolden:
      type: object
      description: Upload url for putting the document
      properties:
        name:
          $ref: '#/components/schemas/DocumentName'
        configuration:
          $ref: '#/components/schemas/AssociatedConfigurationName'
      required:
        - name
      additionalProperties: false
    PutGolden:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/DocumentName'
        configuration:
          $ref: '#/components/schemas/AssociatedConfigurationName'
      additionalProperties: false

    AssociatedConfigurationName:
      type: string
      pattern: ^[a-z0-9_]*$
      minLength: 3
      maxLength: 128
      description: User-friendly name of the configuration to associate to the reference document
      example: anyco_auto_insurance_quote

    GetAllConfigurations:
      type: array
      items:
        type: object
        properties:
          name:
            $ref: '#/components/schemas/ConfigurationName'
          created:
            $ref: '#/components/schemas/Date'
          versions:
            type: array
            items:
              $ref: '#/components/schemas/ConfigurationVersion'
        required:
          - name
          - created
          - versions
        additionalProperties: false
    ConfigurationVersion:
      type: object
      properties:
        version_id:
          type: string
          example: fdE0LO4d2GftiGvPyeYbgpstRWyLrEdm
        datetime:
          $ref: '#/components/schemas/Date'
          description: >-
            The date and time Sensible created this version ID for the config.
            Sensible creates a new version ID for a config when you:
            1. publish a config to an environment in the Sensible app
            2. create or edit the configuration through the Sensible API. Publishing or unpublishing an
               existing configuration version using the Sensible API doesn't trigger the creation of a new version ID.
        environments:
          type: array
          items:
            type: string
          example: [production, development]
        draft:
          type: boolean
          example: false
          description: >-
            The version list returned by this endpoint contains a single draft version ID that's used to manage the editor state in the Sensible app.
            This draft version ID is never published to the development or production environments.
      required:
        - version_id
        - datetime
        - draft
      additionalProperties: false


    PostConfiguration:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ConfigurationName'
        configuration:
          $ref: '#/components/schemas/StringifiedConfigurationRequest'
          example: |
            { 	"fingerprint": { 		"tests": [ 			"anyco", 			"quoted coverage changes" 		] 	}, 	"preprocessors": [{ 		"type": "pageRange", 		"startPage": 0, 		"endPage": 2 	}], 	"fields": [{ 		"id": "_driver_name_raw", 		"anchor": "name of driver", 		"method": { 			"id": "label", 			"position": "below" 		} 	}], 	"computed_fields": [{ 			"id": "driver_name_last", 			"method": { 				"id": "split", 				"source_id": "_driver_name_raw", 				"separator": ", ", 				"index": 1 			} 		}  	] }
        publish_as:
          $ref: '#/components/schemas/Environment'
      required:
        - name
        - configuration
      additionalProperties: false
    StringifiedConfigurationRequest:
      type: string
      description: |
        JSON-stringified configuration.
        If you test this endpoint using the **Try It** button in this interactive API explorer,
        the explorer stringifies the JSON for you when you paste the configuration into this parameter.
        To support publishing drafts, this API doesn’t reject requests with configuration errors.
        To validate, compare your configuration to the latest version of the configuration schema, published at https://schema.sensible.so/configuration.schema.json.



    Environment:
      type: string
      enum: [production, development]
      minLength: 3
      maxLength: 128
      example: development
      description: >-
        Destination environment for publication, as a target for later extraction.
        If you specify an environment, the configuration must be valid.
        If you don't specify an environment, Sensible saves this version of the configuration as the current draft.


    ConfigurationResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ConfigurationName'
        created:
          $ref: '#/components/schemas/Date'
        configuration:
          type: string
          description: Configuration returned as stringified JSON.
          example: |
            "{\r\n\t\"fingerprint\": {\r\n\t\t\"tests\": [\r\n\t\t\t\"anyco\",\r\n\t\t\t\"quoted coverage changes\"\r\n\t\t]\r\n\t},\r\n\t\"preprocessors\": [{\r\n\t\t\"type\": \"pageRange\",\r\n\t\t\"startPage\": 0,\r\n\t\t\"endPage\": 2\r\n\t}],\r\n\t\"fields\": [{\r\n\t\t\"id\": \"_driver_name_raw\",\r\n\t\t\"anchor\": \"name of driver\",\r\n\t\t\"method\": {\r\n\t\t\t\"id\": \"label\",\r\n\t\t\t\"position\": \"below\"\r\n\t\t}\r\n\t}],\r\n\t\"computed_fields\": [{\r\n\t\t\t\"id\": \"driver_name_last\",\r\n\t\t\t\"method\": {\r\n\t\t\t\t\"id\": \"split\",\r\n\t\t\t\t\"source_id\": \"_driver_name_raw\",\r\n\t\t\t\t\"separator\": \", \",\r\n\t\t\t\t\"index\": 1\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t]\r\n}"
        version_id:
          type: string
        versions:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationVersion'
      required:
        - name
        - created
        - configuration
        - version_id
        - versions
      additionalProperties: false
    PutConfiguration:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
        configuration:
          $ref: '#/components/schemas/StringifiedConfigurationRequest'
          example: |
            { "fields": [{ 		"id": "updated_name_field", 		"anchor": "name of driver", 		"method": { 			"id": "label", 			"position": "below" 		} 	}], 	"computed_fields": [{ 			"id": "driver_name_last", 			"method": { 				"id": "split", 				"source_id": "_driver_name_raw", 				"separator": ", ", 				"index": 1 			} 		}  	] }


        publish_as:
          $ref: '#/components/schemas/Environment'
        current_draft:
          type: string
          description: >-
            Version ID of the current draft of the configuration, if the current draft exists and is being replaced.
            if the configuration is currently in draft and this parameter is not supplied or does not match, the operation fails
      additionalProperties: false

    PublishConfigurationVersion:
      type: object
      properties:
        publish_as:
          $ref: '#/components/schemas/Environment'
      required:
        - publish_as
      additionalProperties: false
    ConfigurationVersionsResponse:
      type: object
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationVersion'
      required:
        - versions
      additionalProperties: false
    PostGoldenExtraction:
      type: object
      properties:
        golden:
          type: string
          description: user-friendly name for the reference document
          example: best_scan_doc_num_1234
        configuration:
          type: object
          description: >-
            SenseML configuration as a JSON object, not stringified JSON, for example, `"configuration": {"fields":[]}`.
            If you leave out this parameter, then Sensible returns the best-scoring extraction
            from the configurations in the document type.  If you specify it, Sensible ignores the `environment` parameter.
          example: {"fields":[]}

    # NOTE: all the Extraction schema stuff is duplicated in openapi.yml it would be nicer to single source them but then we'd need a tool to combine the ymls since readme-cli doesn't seem to handle it well...
    ResponseGoldenExtraction:
      allOf:
        - $ref: '#/components/schemas/Extraction'
        - type: object
          properties:
            parsed_document_with_metadata:
              type: object
              description: the verbose extraction output, including information about line coordinates.
            errors:
              type: array
              description: extraction errors. See an extraction endpoint's response schema for more information.
            text:
              $ref: '#/components/schemas/ResponseStandardText'
              description: >-
                All the text in the document. To return this, set `"verbosity": 3"` in the specified configuration
            fingerprints:
              type: object
              description: the page and line indexes for the fingerprints found  # todo - provide example

    Extraction:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ExtractionId'
        created:
          $ref: '#/components/schemas/ExtractionCreated'
        type:
          $ref: '#/components/schemas/ExtractionType'
        configuration:
          type: string
          description: Name of the config (SenseML query) used to extract the structured data. Sensible chooses the best config in the document type that fits the submitted document automatically.
          example: anyco_rate_confirmation
        status:
          $ref: '#/components/schemas/ExtractionStatus'
        parsed_document:
          $ref: '#/components/schemas/ParsedDocument'
        validations:
          $ref: '#/components/schemas/Validations'
        validations_summary:
          $ref: '#/components/schemas/ValidationsSummary'
        classification_summary:
          $ref: '#/components/schemas/ClassificationSummary'

    ParsedDocument:
      description: Data extracted from the document, structured as an array of fields
      type: object
      example:
        weight:
          source: 0.0lbs
          value: 0
          unit: pounds
          type: weight
        distance:
          source: 193mi
          value: 193
          unit: miles
          type: distance
        load_number:
          type: string
          value: Wk91242
        carrier_email: null
        price:
          source: $695.00
          value: 695
          unit: $
          type: currency
        pickup_date: null
    ResponseStandardText:
      description: >-
        all the text in the document, standardized as an array of pages with lines and their metadata, including positioning
      type: object
      example:
        pages:
        - width: 8.5
          height: 11
          rotation: 0
          transform:
            a: 1
            c: 0
            e: 0
            b: 0
            d: 1
            f: 0
          lines:
          - text: Extract your first data
            boundingPolygon:
            - x: 1.111
              y: 0.472
            - x: 4.661
              y: 0.472
            - x: 4.661
              y: 0.806
            - x: 1.111
              y: 0.806
          - text: Hello world!
            boundingPolygon:
            - x: 0.444
              y: 1.792
            - x: 2.07
              y: 1.792
            - x: 2.07
              y: 2.083
            - x: 0.444
              y: 2.083
          - text: Inside documents,
            boundingPolygon:
            - x: 4.25
              y: 2.042
            - x: 5.982
              y: 2.042
            - x: 5.982
              y: 2.236
            - x: 4.25
              y: 2.236

    ValidationRequest:
      type: object
      additionalProperties: false
      description: See https://docs.sensible.so/docs/validate-extractions.
      properties:
        description:
          type: string
          description: User-friendly description for the test
          example: Broker's email is in string@string format
        condition:
          description: The test for extraction written in JsonLogic.
          example: {"match":[{"var":"broker\\.email.value"},"^\\S+\\@\\S+$"]}
          type: object
          additionalProperties: true
        fields:
          type: array
          description: Skip this test unless prerequisite fields are non-null.
          example: ["broker\\.email"]
          items:
            type: string
        severity:
          type: string
          description: Severity of the failing test
          enum:
            - warning
            - error
      required:
        - description
        - condition

    ValidationResponse:
      type: object
      properties:
        description:
          type: string
          description: Description of the validation
          example: Dollar amount should be more than $100
        severity:
          type: string
          enum: [error, warning, skipped]
          example: warning
          description: Severity of the failing validation (error, warning, skipped)
        message:
          type: string
          description: Messages about why the validation failed
          example: >-
            Missing prerequisites: broker.email




    Validations:
      description: Which extracted fields failed validation rules you write in the Sensible app
      type: array
      items:
        $ref: '#/components/schemas/ValidationResponse'
      example:
        - description: Load weight should be over 1 ton
          severity: warning
        - description: Carrier email must be in format string@string
          severity: skipped
          message: Missing prerequisites - carrier_email

    ValidationsSummary:
      type: object
      description: Summary of the extracted fields that failed validation rules you write in the Sensible app.
      properties:
        fields:
          type: integer
          description: Number of fields specified in the SenseML config to extract from the document
          example: 6
        fields_present:
          type: integer
          description: Actual number of non-null fields extracted from the document
          example: 4
        errors:
          type: number
          description: Number of errors in the extraction
          example: 0
        warnings:
          type: number
          description: Number of warnings in the extraction
          example: 1
        skipped:
          type: integer
          description: Number of fields skipped in the extraction because a prerequisite field was null
          example: 1


    ExtractionId:
      type: string
      format: uuid
      description: Unique ID for the extraction, used to retrieve the extraction
      example: 246a6f60-0e5b-11eb-b720-295a6fba723e

    ExtractionCreated:
      type: string
      format: date
      description: Date the extraction was created

    ExtractionType:
      type: string
      description: User-friendly name of the document type
      example: rate_confirmation
    ExtractionStatus:
      type: string
      description: Extraction status (WAITING, COMPLETE, FAILED)
      enum: [WAITING, COMPLETE, FAILED]
      example: COMPLETE

    ClassificationSummary:
      type: array
      description:  >-
            Metadata about how Sensible chose the config to use for this extraction.
            Sensible compares all configs in the document type, then chooses the best extraction using
            fingerprints, scores, or a combination of the two.
            (When two extractions tie by score and fingerprints, Sensible chooses the
            first configuration in alphabetic order).
            For more details, see [fingerprints](https://docs.sensible.so/docs/fingerprint#notes)
      items:
        $ref: '#/components/schemas/Classification'
      example:
        - configuration: anyco_rate_confirmation
          fingerprints: 2
          fingerprints_present: 2
          score:
            value: 3
            fields_present: 4
            penalities: 0.5
        - configuration: acme_co
          fingerprints: 2
          fingerprints_present: 2
          score:
            value: 0
            fields_present: 2
            penalities: 1.5
    Classification:
      type: object
      properties:
        configuration:
          type: string
          example: anyco
          description: The config tested for fingerprints
        fingerprint_present:
          type: integer
          example: 1
          description: The number of this config's fingerprints that Sensible found in the document.
        fingerprints:
          type: integer
          example: 1
          description: The number of fingerprints defined in this config.
        score:
          $ref: '#/components/schemas/Score'

    Score:
      type: object
      description: The score for the extraction, used to help choose the best extraction.
      properties:
        value:
          type: number
          example: 17
          description: The score total is fields_present minus penalty points. In the absence of fingerprints, Sensible returns the extraction in the document type with the highest score.
        fields_present:
          type: integer
          example: 17
          description: Number of non-null fields Sensible extracted from the document using this config
        penalties:
          type: number
          example: 1.5
          description: Errors are 1 penality point and warnings are 0.5 points. See the validations_summary for a breakdown.

  responses:
    204:
      description: No content
      content:
        text/plain:
          schema:
            title: No Content
            type: string
            example: No Content
    400:
      description: Bad Request
      content:
        text/plain:
          schema:
            title: Bad Request
            type: string
            example: >-
              Either a specific set of messages about fields in the request, or error messages like the following examples -
              Not available to logged in users
              To use the asynchronous flow you must have persistence enabled
              Specified document type does not exist
              Specified document type ${named type} does not exist
              No published configurations found for environment ${environment}
              Specified golden does not exist
              Specified configuration/version does not exist
              Specified configuration/version is not valid
              Must provide the Content-Type header when request body is present
              Content-Type must be application/json
              Missing request body or body.document
              Could not determine the content type of the document
              Could not determine the content type of the document. Please check that the document was correctly encoded as Base64
              This PDF is invalid. If you submitted this PDF using Base64 encoding, please check that the encoding is correct
              This PDF is password protected. Please resubmit with password protection disabled
              This PDF is empty
              This PDF exceeds the maximum dimensions for OCR of 17 x 17 inches
              This PDF exceeds the maximum size for OCR of 50MB
              No fingerprints match for this PDF and fingerprint_mode is set to strict
              Content type of ${found} does not match declared type of ${expected}
              Document is not present
    401:
      description: Not authorized
      content:
        text/plain:
          schema:
            title: Unauthorized
            type: string
            example: Unauthorized
    404:
      description: Not Found
      content:
        text/plain:
          schema:
            title: Not Found
            type: string
    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 to extract data from.
    # 429:
    #   description: Too Many Requests
    #   content:
    #     text/plain:
    #       schema:
    #         title: Unsupported Media Type
    #         type: string
    #         example: >-
    #           Example 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
  securitySchemes:
    bearerAuth:       # arbitrary name for the security scheme
      type: http
      scheme: bearer
      description: >-
        Sensible uses API keys to authenticate requests.
        Keep your API keys secure and do not share them publicly accessible areas such as GitHub, client-side code, etc.
        Authentication to the API is performed via Bearer Authentication. Provide your API key as the bearer auth value.
# Apply the auth globally to all operations
security:
  - bearerAuth: []