LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
{
"components": {
"schemas": {
"APIDeploymentSummary": {
"description": "One API deployment, as it appears in an organisation's listing.\n\n`api_name` and `api_endpoint` are what an execution call needs;\n`display_name` and `description` say what the deployment is for.",
"properties": {
"api_endpoint": {
"readOnly": true,
"type": "string"
},
"api_name": {
"maxLength": 30,
"readOnly": true,
"type": "string"
},
"co_owners_count": {
"readOnly": true,
"type": "integer"
},
"created_by": {
"nullable": true,
"readOnly": true,
"type": "integer"
},
"created_by_email": {
"description": "Get the email of the creator.",
"nullable": true,
"readOnly": true,
"type": "string"
},
"description": {
"maxLength": 255,
"readOnly": true,
"type": "string"
},
"display_name": {
"maxLength": 30,
"readOnly": true,
"type": "string"
},
"id": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"is_active": {
"readOnly": true,
"type": "boolean"
},
"is_owner": {
"readOnly": true,
"type": "boolean"
},
"last_5_run_statuses": {
"description": "Fetch the last 5 execution statuses with timestamps for this API deployment.",
"items": {
"additionalProperties": {},
"type": "object"
},
"readOnly": true,
"type": "array"
},
"last_run_time": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"owner_emails": {
"description": "Email of each owner, earliest first. Empty if none is a person.",
"items": {
"type": "string"
},
"readOnly": true,
"type": "array"
},
"run_count": {
"readOnly": true,
"type": "integer"
},
"workflow": {
"format": "uuid",
"type": "string"
},
"workflow_name": {
"readOnly": true,
"type": "string"
}
},
"required": [
"api_endpoint",
"api_name",
"co_owners_count",
"created_by",
"created_by_email",
"description",
"display_name",
"id",
"is_active",
"is_owner",
"last_5_run_statuses",
"last_run_time",
"owner_emails",
"run_count",
"workflow",
"workflow_name"
],
"type": "object"
},
"AcknowledgedResponse": {
"description": "The execution's result was handed to an earlier call and discarded.",
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"message",
"status"
],
"type": "object"
},
"ApiKeyPermission": {
"description": "* `read` - Read\n* `read_write` - Read/Write\n* `full_access` - Full Access",
"enum": [
"read",
"read_write",
"full_access"
],
"type": "string"
},
"DeploymentErrorResponse": {
"description": "The body of a rejected execute request.\n\nCarries `message.error` as well, so a client can read the failure from the\nkey an execution reports it in, whatever went wrong.",
"properties": {
"errors": {
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": "array"
},
"message": {
"$ref": "#/components/schemas/ErrorMessage"
},
"type": {
"$ref": "#/components/schemas/ErrorType"
}
},
"required": [
"errors",
"message",
"type"
],
"type": "object"
},
"ErrorDetail": {
"description": "One problem found with the request.",
"properties": {
"attr": {
"description": "The request field the problem belongs to, when it belongs to one.",
"nullable": true,
"type": "string"
},
"code": {
"description": "Machine-readable problem identifier.",
"type": "string"
},
"detail": {
"description": "Human-readable description.",
"type": "string"
}
},
"required": [
"attr",
"code",
"detail"
],
"type": "object"
},
"ErrorMessage": {
"description": "The failure in the same place an execution reports its own.",
"properties": {
"error": {
"description": "Every problem in `errors`, as one readable string.",
"type": "string"
},
"execution_status": {
"description": "Always `ERROR`.",
"type": "string"
}
},
"required": [
"error",
"execution_status"
],
"type": "object"
},
"ErrorResponse": {
"description": "The body of a rejected request.\n\nProduced by the project-wide exception handler, so its shape is the same\nfor every failure listed against an operation.",
"properties": {
"errors": {
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": "array"
},
"type": {
"$ref": "#/components/schemas/ErrorType"
}
},
"required": [
"errors",
"type"
],
"type": "object"
},
"ErrorType": {
"description": "* `validation_error` - validation_error\n* `client_error` - client_error\n* `server_error` - server_error",
"enum": [
"validation_error",
"client_error",
"server_error"
],
"type": "string"
},
"ExecuteRequest": {
"description": "The documents to run, and the options that shape the result.\n\nSupply `files`, `presigned_urls`, or both.",
"properties": {
"custom_data": {
"nullable": true
},
"files": {
"items": {
"format": "binary",
"type": "string"
},
"type": "array"
},
"hitl_packet_id": {
"description": "Groups documents reviewed together into one packet. Requires the enterprise manual-review capability; an installation without it rejects the request with 400.",
"nullable": true,
"type": "string"
},
"hitl_queue_name": {
"description": "Document class name for the manual review queue. Requires the enterprise manual-review capability; an installation without it rejects the request with 400.",
"nullable": true,
"type": "string"
},
"include_extracted_text": {
"default": false,
"type": "boolean"
},
"include_metadata": {
"default": false,
"type": "boolean"
},
"include_metrics": {
"default": false,
"type": "boolean"
},
"llm_profile_id": {
"nullable": true,
"type": "string"
},
"presigned_urls": {
"items": {
"format": "uri",
"type": "string"
},
"type": "array"
},
"tags": {
"default": "",
"description": "Comma-separated list of tag names (EX:'tag1,tag2-name,tag3_name')",
"type": "string"
},
"timeout": {
"default": -1,
"maximum": 300,
"minimum": -1,
"type": "integer"
}
},
"type": "object"
},
"ExecuteResponse": {
"properties": {
"message": {
"$ref": "#/components/schemas/ExecutionMessage"
}
},
"required": [
"message"
],
"type": "object"
},
"ExecutionMessage": {
"description": "The execution's identity and, once it has finished, its per-file\nresults.",
"properties": {
"error": {
"nullable": true,
"type": "string"
},
"execution_id": {
"type": "string"
},
"execution_status": {
"type": "string"
},
"result": {
"items": {
"$ref": "#/components/schemas/FileResult"
},
"nullable": true,
"type": "array"
},
"status_api": {
"nullable": true,
"type": "string"
}
},
"required": [
"execution_id",
"execution_status"
],
"type": "object"
},
"FileResult": {
"description": "One input document's outcome.\n\nEvery key is present on every item; the ones that depend on the request\noptions or on the outcome are sent as `null` when they do not apply.",
"properties": {
"error": {
"nullable": true,
"type": "string"
},
"extracted_text": {
"description": "The document's full extracted text. Sent only when the request set `include_extracted_text`.",
"nullable": true,
"type": "string"
},
"file": {
"type": "string"
},
"file_execution_id": {
"nullable": true,
"type": "string"
},
"metadata": {
"nullable": true
},
"result": {
"nullable": true
},
"status": {
"type": "string"
}
},
"required": [
"file"
],
"type": "object"
},
"PaginatedAPIDeploymentSummaryList": {
"properties": {
"count": {
"example": 123,
"type": "integer"
},
"next": {
"example": "http://api.example.org/accounts/?page=4",
"format": "uri",
"nullable": true,
"type": "string"
},
"previous": {
"example": "http://api.example.org/accounts/?page=2",
"format": "uri",
"nullable": true,
"type": "string"
},
"results": {
"items": {
"$ref": "#/components/schemas/APIDeploymentSummary"
},
"type": "array"
}
},
"required": [
"count",
"results"
],
"type": "object"
},
"PlatformKeyError": {
"description": "Why a platform-key request was refused.\n\nProduced by the authentication middleware rather than by the project's\nexception handler, so it carries a single human-readable message and none\nof the per-field structure the organisation-scoped endpoints return. It is\nthe shape of this operation's credential failures specifically, not of\nevery failure it can return.",
"properties": {
"message": {
"description": "Human-readable reason for the refusal.",
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"StatusResponse": {
"properties": {
"message": {
"items": {
"$ref": "#/components/schemas/FileResult"
},
"nullable": true,
"type": "array"
},
"status": {
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
"WhoAmIResponse": {
"description": "The organisation a platform API key belongs to, and what it may do.",
"properties": {
"key_name": {
"description": "The key's name, as it was minted.",
"type": "string"
},
"organization_id": {
"description": "The organisation's identifier, as it appears in web-app URLs and in every organisation-scoped API path.",
"type": "string"
},
"organization_name": {
"description": "The organisation's display name.",
"type": "string"
},
"permission": {
"allOf": [
{
"$ref": "#/components/schemas/ApiKeyPermission"
}
],
"description": "The key's permission tier, which decides the HTTP methods it may issue.\n\n* `read` - Read\n* `read_write` - Read/Write\n* `full_access` - Full Access"
}
},
"required": [
"key_name",
"organization_id",
"organization_name",
"permission"
],
"type": "object"
}
},
"securitySchemes": {
"deploymentKey": {
"description": "A key that runs an API deployment: the deployment's own key, or a global API deployment key with access to it.",
"scheme": "bearer",
"type": "http"
},
"platformKey": {
"description": "An organisation-wide platform API key, minted under Settings. It carries the organisation it belongs to, but cannot execute an API deployment.",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"title": "Unstract API",
"version": "v1"
},
"openapi": "3.0.3",
"paths": {
"/api/v1/unstract/whoami/": {
"get": {
"description": "Takes a platform API key and nothing else: the organisation is read from the key itself, so this route carries no organisation segment. Call it once and store `organization_id`; every other endpoint takes it as a path segment.\n\nAn API deployment key is rejected as unauthenticated.",
"operationId": "whoami",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhoAmIResponse"
}
}
},
"description": ""
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformKeyError"
}
}
},
"description": "No usable platform API key was supplied \u2014 absent, malformed, unknown, or revoked."
},
"500": {
"description": "The request could not be served. The body is not guaranteed to be JSON."
}
},
"security": [
{
"platformKey": []
}
],
"summary": "Resolve the organisation a platform key belongs to",
"tags": [
"identity"
]
}
},
"/api/v1/unstract/{org_id}/api/deployment/": {
"get": {
"description": "Lists what an organisation has deployed, authenticated by a platform API key that belongs to it.\n\nA deployment key is not part of this listing; executing a deployment still needs one.\n\nOrdered by most recent run first, then by identifier, so paging is stable.",
"operationId": "list_deployments",
"parameters": [
{
"description": "Return only the deployment with exactly this `api_name`.",
"in": "query",
"name": "api_name",
"schema": {
"type": "string"
}
},
{
"description": "Which field to use when ordering the results.",
"in": "query",
"name": "ordering",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "A page number within the paginated result set.",
"in": "query",
"name": "page",
"required": false,
"schema": {
"type": "integer"
}
},
{
"description": "Number of results to return per page.",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"type": "integer"
}
},
{
"description": "Return only deployments whose display name contains this text, case-insensitively.",
"in": "query",
"name": "search",
"schema": {
"type": "string"
}
},
{
"description": "Return only the deployments of this workflow.",
"in": "query",
"name": "workflow",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The organisation the request is scoped to, as `whoami` reports it in `organization_id`.",
"in": "path",
"name": "org_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedAPIDeploymentSummaryList"
}
}
},
"description": "One page of the organisation's API deployments."
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "A query parameter was malformed."
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformKeyError"
}
}
},
"description": "No usable platform API key was supplied \u2014 absent, malformed, unknown, or revoked."
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformKeyError"
}
}
},
"description": "The key was recognised but refused: it does not belong to the organisation named in the path, or its permission tier is not one this deployment knows."
},
"500": {
"description": "The request could not be served. The body is not guaranteed to be JSON."
}
},
"security": [
{
"platformKey": []
}
],
"summary": "List an organisation's API deployments",
"tags": [
"deployment"
]
}
},
"/deployment/api/{org_name}/{api_name}/": {
"get": {
"description": "Reads a previously started execution, taking the same deployment key that ran it. The read is one-shot: the first call that observes a completed execution acknowledges it and the stored result is discarded, so every later call for that execution answers 406. Keep the payload of the call that returns it \u2014 it cannot be fetched again.\n\nA still-running execution answers 422 carrying its current `status`, so a polling loop should treat 422 as the normal reply and stop on 200.",
"operationId": "status",
"parameters": [
{
"description": "API deployment name.",
"in": "path",
"name": "api_name",
"required": true,
"schema": {
"pattern": "^[\\w-]+$",
"type": "string"
}
},
{
"in": "query",
"name": "execution_id",
"required": true,
"schema": {
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "include_extracted_text",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"in": "query",
"name": "include_metadata",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"in": "query",
"name": "include_metrics",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Organization identifier.",
"in": "path",
"name": "org_name",
"required": true,
"schema": {
"pattern": "^[\\w-]+$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusResponse"
}
}
},
"description": ""
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The request failed validation."
},
"401": {
"content": {
"application/json": {
"examples": {
"AuthenticationFailed": {
"value": {
"errors": [
{
"attr": null,
"code": "authentication_failed",
"detail": "Incorrect authentication credentials."
}
],
"type": "client_error"
}
},
"NotAuthenticated": {
"value": {
"errors": [
{
"attr": null,
"code": "not_authenticated",
"detail": "Authentication credentials were not provided."
}
],
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No usable API key was supplied for the deployment."
},
"403": {
"content": {
"application/json": {
"examples": {
"PermissionDenied": {
"value": {
"errors": [
{
"attr": null,
"code": "permission_denied",
"detail": "You do not have permission to perform this action."
}
],
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "The request was refused as unauthorized."
},
"404": {
"content": {
"application/json": {
"examples": {
"NotFound": {
"value": {
"errors": [
{
"attr": null,
"code": "not_found",
"detail": "Not found."
}
],
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "No active deployment, or a referenced document, was found."
},
"406": {
"content": {
"application/json": {
"examples": {
"NotAcceptable": {
"value": {
"errors": [
{
"attr": null,
"code": "not_acceptable",
"detail": "Could not satisfy the request Accept header."
}
],
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/AcknowledgedResponse"
}
}
},
"description": "The result was already consumed by an earlier call."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatusResponse"
}
}
},
"description": "The execution is still running, or it finished with an error; read `status` to tell them apart."
},
"500": {
"content": {
"application/json": {
"examples": {
"APIException": {
"value": {
"errors": [
{
"attr": null,
"code": "error",
"detail": "A server error occurred."
}
],
"type": "server_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/StatusResponse"
}
}
},
"description": "The execution could not be completed; the body carries its last known state."
}
},
"security": [
{
"deploymentKey": []
}
],
"summary": "Read the result of an execution",
"tags": [
"deployment"
]
},
"post": {
"description": "Runs an API deployment. Takes a deployment key \u2014 either the deployment's own key, or a global API deployment key that has access to it.\n\nSupply the documents either as `files` (multipart upload) or as `presigned_urls` (HTTPS S3 URLs), or both \u2014 a request carrying neither is rejected, and the two together may not exceed 32 documents.\n\nWith the default `timeout` of -1 the call returns as soon as the execution is queued; read the outcome from the status endpoint.",
"operationId": "execute",
"parameters": [
{
"description": "API deployment name.",
"in": "path",
"name": "api_name",
"required": true,
"schema": {
"pattern": "^[\\w-]+$",
"type": "string"
}
},
{
"description": "Organization identifier.",
"in": "path",
"name": "org_name",
"required": true,
"schema": {
"pattern": "^[\\w-]+$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/ExecuteRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteResponse"
}
}
},
"description": ""
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "The request failed validation."
},
"401": {
"content": {
"application/json": {
"examples": {
"AuthenticationFailed": {
"value": {
"errors": [
{
"attr": null,
"code": "authentication_failed",
"detail": "Incorrect authentication credentials."
}
],
"message": {
"error": "Incorrect authentication credentials.",
"execution_status": "ERROR"
},
"type": "client_error"
}
},
"NotAuthenticated": {
"value": {
"errors": [
{
"attr": null,
"code": "not_authenticated",
"detail": "Authentication credentials were not provided."
}
],
"message": {
"error": "Authentication credentials were not provided.",
"execution_status": "ERROR"
},
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "No usable API key was supplied for the deployment."
},
"403": {
"content": {
"application/json": {
"examples": {
"PermissionDenied": {
"value": {
"errors": [
{
"attr": null,
"code": "permission_denied",
"detail": "You do not have permission to perform this action."
}
],
"message": {
"error": "You do not have permission to perform this action.",
"execution_status": "ERROR"
},
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "The request was refused as unauthorized."
},
"404": {
"content": {
"application/json": {
"examples": {
"NotFound": {
"value": {
"errors": [
{
"attr": null,
"code": "not_found",
"detail": "Not found."
}
],
"message": {
"error": "Not found.",
"execution_status": "ERROR"
},
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "No active deployment, or a referenced document, was found."
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "A referenced document is larger than the limit."
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteResponse"
}
}
},
"description": "The execution finished with an error."
},
"429": {
"content": {
"application/json": {
"examples": {
"Throttled": {
"value": {
"errors": [
{
"attr": null,
"code": "throttled",
"detail": "Request was throttled."
}
],
"message": {
"error": "Request was throttled.",
"execution_status": "ERROR"
},
"type": "client_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "Too many concurrent executions; retry later."
},
"500": {
"content": {
"application/json": {
"examples": {
"APIException": {
"value": {
"errors": [
{
"attr": null,
"code": "error",
"detail": "A server error occurred."
}
],
"message": {
"error": "A server error occurred.",
"execution_status": "ERROR"
},
"type": "server_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ExecuteResponse"
}
}
},
"description": "The deployment could not be run; the body carries the execution that failed."
},
"502": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "A referenced document could not be fetched."
},
"504": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeploymentErrorResponse"
}
}
},
"description": "Fetching a referenced document timed out."
}
},
"security": [
{
"deploymentKey": []
}
],
"summary": "Execute an API deployment against documents",
"tags": [
"deployment"
]
}
}
},
"tags": [
{
"description": "Discover an organisation's API deployments, run one against one or more documents, and poll the result.",
"name": "deployment"
},
{
"description": "Resolve what a platform API key is scoped to, so a client can discover its organisation rather than being told it.",
"name": "identity"
}
]
}