{ "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": { "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", "description": "Lists all document types in your Sensible 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:\n\n```curl\ncurl --location --request PUT 'https://api.sensible.so/v0/document_types/' \\\n--header 'Authorization: Bearer YOUR_API_KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"schema\":{\"validations\":[{\"description\":\"example validation to test broker email format\",\"condition\":{\"match\":[{\"var\":\"broker\\\\.email.value\"},\"^\\\\S+\\\\@\\\\S+$\"]},\"severity\":\"warning\",\"fields\":[\"test\"]}]}} '\n```\n", "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", "scope": [ "pay_section" ] } ] } } } } }, "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,\nbut not its extraction history displayed in the Sensible app.\n", "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" } } } }, "/extract_text_from_golden/{type-name}": { "parameters": [ { "$ref": "#/components/parameters/documentTypeName" } ], "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": { "type": "object", "properties": { "text": { "$ref": "#/components/schemas/ResponseStandardText" } }, "required": [ "text" ], "additionalProperties": false } } }, "description": "All the text in the document, wrapped in a `text` property" }, "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/Name" } }, "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": { "type": "string", "pattern": "^[a-z0-9_]+$", "minLength": 3, "maxLength": 128, "description": "User-friendly name", "example": "insurance_quote", "x-internal-note": "Single shared schema covers config names, document type names, and golden names. You can achieve context-specific examples for the purpose of the API docs ('auto_insurance_quotes_all_carriers', 'anyco_carrier', 'insurance_quote_john_doe' for doc type, config, and document, for example) using allOf wrappers at each usage site, but we're not bothering right now, given codegen is a primary consumer and a single neutral example is sufficient." }, "Date": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time." }, "DocumentType": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "id": { "$ref": "#/components/schemas/UniqueId" }, "created": { "$ref": "#/components/schemas/Date" }, "schema": { "$ref": "#/components/schemas/DocumentTypeOutput" } }, "x-internal-note": "processor_type is accepted on POST and returned on GET but has no functional effect — it is never read by any backend logic to gate behavior or filter operations. Added during early email processor development, never productized. Omitting from the public spec for now (same treatment as prevent_file_metadata).", "required": [ "name", "id", "created", "schema" ], "additionalProperties": false }, "GetAllDocumentTypes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" } }, "PostDocumentType": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "schema": { "$ref": "#/components/schemas/DocumentTypeOutput" } }, "required": [ "name", "schema" ], "additionalProperties": false }, "DocumentTypeOutput": { "type": "object", "additionalProperties": false, "x-internal-note": "prevent_file_metadata is returned by the backend but omitted here -- not documenting for now, not a lot of demand for it and not really productized at the moment.", "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](doc:ocr-engine).\n" }, "prevent_default_merge_lines": { "type": "boolean", "description": "Prevents the built-in line merging that occurs before the\n[Merge Lines](doc:merge-lines) preprocessor.\n" }, "ocr_level": { "enum": [ 0, 2, 4, 5 ], "type": "number", "description": "See [OCR level](doc:ocr-level).\n" }, "validations": { "description": "Array of validations. See [Validating extractions](doc:validate-extractions).", "items": { "$ref": "#/components/schemas/Validation" }, "type": "array" }, "review_triggers": { "description": "Criteria for flagging an extraction for [human review](doc:human-review). If the review criteria includes specific validations, this parameter contains `selected_validations` set to `true`. Set `needs_review` to `true` on individual validations in the `validations` array to select them.", "type": "object", "properties": { "coverage_threshold": { "type": "number", "description": "Inclusive upper bound (0-1) for coverage score. Extractions scoring below this value are flagged for review." }, "validation_errors_threshold": { "type": "integer", "description": "Inclusive lower bound for the number of validation errors that flags an extraction for review." }, "validation_warnings_threshold": { "type": "integer", "description": "Inclusive lower bound for the number of validation warnings that flags an extraction for review." }, "selected_validations": { "type": "boolean", "enum": [ true ], "description": "Present and `true` when the user configured specific validations to trigger review by setting `needs_review` to `true` on those validations." } }, "additionalProperties": false }, "description": { "type": "string", "description": "User-friendly description of the document type." } } }, "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": { "id": { "$ref": "#/components/schemas/UniqueId" }, "name": { "$ref": "#/components/schemas/Name" }, "created": { "$ref": "#/components/schemas/Date" }, "configuration": { "$ref": "#/components/schemas/Name" }, "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" }, "converted_url": { "type": "string", "description": "If present, the URL to GET the PDF Sensible converted this reference document to (present only when the uploaded document wasn't already a PDF)" } }, "required": [ "id", "name", "created" ], "additionalProperties": false }, "PostGolden": { "type": "object", "description": "Upload url for putting the document", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "configuration": { "$ref": "#/components/schemas/Name" }, "content_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/tiff", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "application/vnd.ms-excel.sheet.macroenabled.12", "text/csv", "application/json" ], "description": "Content type of the document you'll upload to `upload_url`." } }, "required": [ "name" ], "additionalProperties": false }, "PutGolden": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "configuration": { "$ref": "#/components/schemas/Name" } }, "additionalProperties": false }, "GetAllConfigurations": { "type": "array", "items": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "created": { "$ref": "#/components/schemas/Date" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationVersion" } }, "editor": { "$ref": "#/components/schemas/ConfigurationEditor" } }, "required": [ "name", "created", "versions" ], "additionalProperties": false } }, "ConfigurationVersion": { "type": "object", "properties": { "version_id": { "type": "string", "example": "fdE0LO4d2GftiGvPyeYbgpstRWyLrEdm", "x-internal-note": "version_id is returned by the backend but deliberately not documented publicly." }, "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\n 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." }, "note": { "type": "string", "description": "Optional user-supplied note describing this version." }, "published_by": { "type": "string", "description": "Display name of whoever published this version: the user's full name (or first name, if that's all that's available), or the account name if the request wasn't tied to an individual user." } }, "required": [ "version_id", "datetime", "draft" ], "additionalProperties": false }, "PostConfiguration": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "configuration": { "$ref": "#/components/schemas/StringifiedConfigurationRequest", "example": "{ \t\"fingerprint\": { \t\t\"tests\": [ \t\t\t\"anyco\", \t\t\t\"quoted coverage changes\" \t\t] \t}, \t\"preprocessors\": [{ \t\t\"type\": \"pageRange\", \t\t\"startPage\": 0, \t\t\"endPage\": 2 \t}], \t\"fields\": [{ \t\t\"id\": \"_driver_name_raw\", \t\t\"anchor\": \"name of driver\", \t\t\"method\": { \t\t\t\"id\": \"label\", \t\t\t\"position\": \"below\" \t\t} \t}], \t\"computed_fields\": [{ \t\t\t\"id\": \"driver_name_last\", \t\t\t\"method\": { \t\t\t\t\"id\": \"split\", \t\t\t\t\"source_id\": \"_driver_name_raw\", \t\t\t\t\"separator\": \", \", \t\t\t\t\"index\": 1 \t\t\t} \t\t} \t] }\n" }, "publish_as": { "$ref": "#/components/schemas/Environment" }, "content_type": { "$ref": "#/components/schemas/ConfigurationContentType" } }, "required": [ "name", "configuration" ], "additionalProperties": false }, "StringifiedConfigurationRequest": { "type": "string", "description": "JSON-stringified configuration.\nIf you test this endpoint using the **Try It** button in this interactive API explorer,\nthe explorer stringifies the JSON for you when you paste the configuration into this parameter.\nTo support publishing drafts, this API doesn’t reject requests with configuration errors.\nTo validate, compare your configuration to the latest version of the configuration schema, published at https://schema.sensible.so/configuration.schema.json.\n" }, "ConfigurationContentType": { "type": "string", "enum": [ "application/json", "application/yaml", "text/csv", "text/plain" ], "description": "Content type of the stringified `configuration`. Defaults to `application/json`." }, "ConfigurationEditor": { "type": "number", "description": "Numeric code indicating the display mode associated with this configuration in the Sensible app. Indicates whether the SenseML editor displays the configuration as JSON or visually, and whether it displays extraction results as JSON or visually." }, "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/Name" }, "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}\"\n" }, "version_id": { "type": "string", "x-internal-note": "version_id is returned by the backend but deliberately not documented publicly." }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationVersion" } }, "content_type": { "$ref": "#/components/schemas/ConfigurationContentType" }, "editor": { "$ref": "#/components/schemas/ConfigurationEditor" } }, "required": [ "name", "created", "configuration", "version_id", "versions", "content_type" ], "additionalProperties": false }, "PutConfiguration": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "configuration": { "$ref": "#/components/schemas/StringifiedConfigurationRequest", "example": "{ \"fields\": [{ \t\t\"id\": \"updated_name_field\", \t\t\"anchor\": \"name of driver\", \t\t\"method\": { \t\t\t\"id\": \"label\", \t\t\t\"position\": \"below\" \t\t} \t}], \t\"computed_fields\": [{ \t\t\t\"id\": \"driver_name_last\", \t\t\t\"method\": { \t\t\t\t\"id\": \"split\", \t\t\t\t\"source_id\": \"_driver_name_raw\", \t\t\t\t\"separator\": \", \", \t\t\t\t\"index\": 1 \t\t\t} \t\t} \t] }\n" }, "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" }, "content_type": { "$ref": "#/components/schemas/ConfigurationContentType" }, "editor": { "$ref": "#/components/schemas/ConfigurationEditor" }, "note": { "type": "string", "description": "Optional note describing this version of the configuration." } }, "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": [] } } }, "required": [ "golden" ] }, "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 } ] } ] } ] } }, "Validation": { "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 validating the field, 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" ] }, "scope": { "type": "array", "description": "If the field to validate is in sections, the list of parent sections.", "items": { "type": "string" }, "example": [ "parent_section", "child_section" ] }, "needs_review": { "type": "boolean", "description": "When true, this validation's failure triggers human review for the extraction." } }, "required": [ "description", "condition" ] } }, "responses": { "204": { "description": "No content. The response has an empty body and no `Content-Type` header." }, "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." } } } }, "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": { "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." } } }, "security": [ { "bearerAuth": [] } ] }