{ "openapi": "3.1.0", "info": { "title": "Batch API", "version": "1.0.0", "summary": "Create a batch of clinical documents and read the results.", "description": "Send clinical documents in a batch and read back coded entities or FHIR R4. Base URL `https://api.amorphous.health`. Authenticate with OAuth 2.0 client credentials." }, "servers": [ { "url": "https://api.amorphous.health" } ], "tags": [ { "name": "Batches", "description": "Create, inspect, submit, cancel, and delete a batch." }, { "name": "Documents", "description": "Add documents to a batch and upload bytes." }, { "name": "Results", "description": "Entities, the NDJSON results stream, and per-document FHIR Bundles." }, { "name": "FHIR", "description": "Patient-level FHIR R4 for live clients. The organization comes from the access token." }, { "name": "OAuth", "description": "Client credentials token endpoint." }, { "name": "Discovery", "description": "OAuth, JWKS, SMART, and health." } ], "paths": { "/v1/data-engine/batches": { "post": { "tags": [ "Batches" ], "operationId": "createBatch", "summary": "Create a Batch", "description": "Optional externalReference makes a retried create return 409 with existingBatchId instead of a second batch.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreate" } } } }, "responses": { "201": { "description": "Batch created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Batches" ], "operationId": "listBatches", "summary": "List Batches", "security": [ { "bearerAuth": [ "batches:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/BatchStatus" } }, { "name": "externalReference", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of batches.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}": { "parameters": [ { "$ref": "#/components/parameters/BatchId" } ], "get": { "tags": [ "Batches" ], "operationId": "getBatch", "summary": "Get a Batch", "description": "Returns a weak ETag. If-None-Match yields 304. Processing batches include Retry-After: 10.", "security": [ { "bearerAuth": [ "batches:read" ] } ], "parameters": [ { "name": "If-None-Match", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The batch.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "ETag": { "description": "Weak ETag, a hash of the body.", "schema": { "type": "string" } }, "Retry-After": { "description": "Present while status is processing. Value is 10.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "304": { "description": "Not modified." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Batches" ], "operationId": "deleteBatch", "summary": "Delete a Batch", "description": "Completed or cancelled batches only. Deletes documents, entities, and files. Final counts are kept for usage reporting. A repeat delete returns 204.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "responses": { "204": { "description": "Deleted, or already deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/submit": { "parameters": [ { "$ref": "#/components/parameters/BatchId" } ], "post": { "tags": [ "Batches" ], "operationId": "submitBatch", "summary": "Submit a Batch", "description": "Pending batches only, with at least one document and none awaiting upload. Live clients need live processing enabled for the organization. A batch already processing returns 200.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "responses": { "200": { "description": "Batch is processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/cancel": { "parameters": [ { "$ref": "#/components/parameters/BatchId" } ], "post": { "tags": [ "Batches" ], "operationId": "cancelBatch", "summary": "Cancel a Batch", "description": "Pending only. Already cancelled returns 200.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "responses": { "200": { "description": "Batch is cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/results": { "parameters": [ { "$ref": "#/components/parameters/BatchId" } ], "get": { "tags": [ "Results" ], "operationId": "streamBatchResults", "summary": "Stream Batch Results", "description": "Completed batches only. Newline-delimited JSON, one document per line.", "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "NDJSON stream.", "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "One ResultLine JSON object per line." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/documents": { "parameters": [ { "$ref": "#/components/parameters/BatchId" } ], "post": { "tags": [ "Documents" ], "operationId": "addDocuments", "summary": "Add Documents", "description": "At most 100 documents and 10 MiB. Atomic. A replay of the same references and checksums returns 200. A mismatch returns 409 and writes nothing.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreate" } } } }, "responses": { "200": { "description": "Replayed page. Existing documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "201": { "description": "Documents created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Documents" ], "operationId": "listDocuments", "summary": "List Documents", "security": [ { "bearerAuth": [ "batches:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/DocumentStatus" } } ], "responses": { "200": { "description": "One page of documents.", "headers": { "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/documents/{documentId}": { "parameters": [ { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a Document", "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Documents" ], "operationId": "deleteDocument", "summary": "Delete a Document", "description": "Pending batch only.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/documents/{documentId}/content": { "parameters": [ { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/DocumentId" } ], "put": { "tags": [ "Documents" ], "operationId": "uploadDocumentContent", "summary": "Upload Document Content", "description": "Raw bytes, at most 25 MiB. Same checksum returns 200. Different bytes after a successful upload return 409.", "security": [ { "bearerAuth": [ "batches:write" ] } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } }, "text/plain": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "responses": { "200": { "description": "Content stored, or the same checksum was sent again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/Unsupported" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/documents/{documentId}/entities": { "parameters": [ { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Results" ], "operationId": "listEntities", "summary": "List Entities", "description": "A document with the same content as an earlier one returns that document's entities.", "security": [ { "bearerAuth": [ "batches:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Entity type, for example Condition." } ], "responses": { "200": { "description": "One page of entities.", "headers": { "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data-engine/batches/{batchId}/documents/{documentId}/fhir": { "parameters": [ { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/DocumentId" } ], "get": { "tags": [ "Results" ], "operationId": "getDocumentFhir", "summary": "Get a FHIR Bundle", "description": "Collection Bundle for one document. Includes a placeholder Patient when the document has no patient.", "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "FHIR collection Bundle.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fhir/R4/metadata": { "get": { "tags": [ "FHIR" ], "operationId": "getFhirCapability", "summary": "Get the Capability Statement", "description": "Live mode only. Any system scope.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "responses": { "200": { "description": "CapabilityStatement.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fhir/R4/Patient/{patientId}": { "get": { "tags": [ "FHIR" ], "operationId": "getFhirPatient", "summary": "Get a Patient", "description": "Live mode only. Needs system/*.rs, system/*.read, or system/Patient.rs or .read.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "parameters": [ { "name": "patientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Patient resource.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fhir/R4/Patient/{patientId}/$everything": { "get": { "tags": [ "FHIR" ], "operationId": "getFhirPatientEverything", "summary": "Get a Patient Everything Bundle", "description": "Live mode only. Returns every type, so it needs system/*.rs or system/*.read.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "parameters": [ { "name": "patientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bundle of every resource for the patient.", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FhirBundle" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fhir/R4/{resourceType}/{resourceId}": { "get": { "tags": [ "FHIR" ], "operationId": "getFhirResource", "summary": "Get a FHIR Resource", "description": "Live mode only. Needs system/*.rs, system/*.read, or system/{resourceType}.rs or .read.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The resource.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/oauth/token": { "post": { "tags": [ "OAuth" ], "operationId": "issueToken", "summary": "Issue an Access Token", "description": "OAuth 2.0 client credentials. Use HTTP Basic for client_secret_basic, or client_assertion for private_key_jwt. Errors follow RFC 6749, not problem+json. No refresh token.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "invalid_request, unsupported_grant_type, invalid_scope, or invalid_grant (assertion jti missing or replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "401": { "description": "invalid_client: unknown client, wrong secret, rejected assertion, or disabled client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "429": { "description": "temporarily_unavailable: too many token requests or failed attempts.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "Discovery" ], "operationId": "getOAuthMetadata", "summary": "Get OAuth Authorization Server Metadata", "security": [], "responses": { "200": { "description": "RFC 8414 metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Discovery" ], "operationId": "getJwks", "summary": "Get JSON Web Key Set", "security": [], "responses": { "200": { "description": "Signing keys for access tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Jwks" } } } } } } }, "/fhir/R4/.well-known/smart-configuration": { "get": { "tags": [ "Discovery" ], "operationId": "getSmartConfiguration", "summary": "Get SMART Configuration", "security": [], "responses": { "200": { "description": "SMART Backend Services configuration.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/health": { "get": { "tags": [ "Discovery" ], "operationId": "getHealth", "summary": "Get Health", "security": [], "responses": { "200": { "description": "Process is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } } } } }, "/health/live": { "get": { "tags": [ "Discovery" ], "operationId": "getLiveness", "summary": "Get Liveness", "security": [], "responses": { "200": { "description": "Process is alive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] } } } } } } }, "/fhir/R4/{resourceType}": { "get": { "tags": [ "FHIR" ], "operationId": "searchFhirResources", "summary": "Search a FHIR Resource Type", "description": "Patient-scoped search. Types other than Patient need patient. Live mode only. Needs system/*.rs, system/*.read, or system/{resourceType}.rs or .read.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Patient ID. Required unless resourceType is Patient." } ], "responses": { "200": { "description": "A searchset Bundle.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "OperationOutcome for a missing or malformed patient.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/fhir/R4/{resourceType}/_search": { "post": { "tags": [ "FHIR" ], "operationId": "searchFhirResourcesPost", "summary": "Search a FHIR Resource Type With POST", "description": "Same as GET search, with parameters in a form body. Live mode only. Needs system/*.rs, system/*.read, or system/{resourceType}.rs or .read.", "security": [ { "bearerAuth": [ "system/*.read" ] } ], "parameters": [ { "name": "resourceType", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "patient": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "A searchset Bundle.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "OperationOutcome for a missing or malformed patient.", "content": { "application/fhir+json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token from POST /oauth/token. Scopes: batches:write, batches:read, and SMART system scopes on /fhir/R4." } }, "parameters": { "BatchId": { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "DocumentId": { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "description": "Page size. Default 50. Maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "description": "nextCursor from the previous page.", "schema": { "type": "string" } } }, "headers": { "RequestId": { "description": "Request ID. Also returned in problem bodies as requestId.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288 link. rel=next when another page exists.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing, expired, or invalid token.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer error=\"invalid_token\"" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Insufficient scope, caller IP not allowed, suspended organization, or a test token on /fhir/R4.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "The ID does not exist for your organization.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Wrong batch state, a retry that does not match, externalReference already used, or live processing not enabled. Create conflicts include existingBatchId.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Invalid": { "description": "Validation error. errors[] carries a JSON Pointer per field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooLarge": { "description": "Body exceeds the route limit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unsupported": { "description": "Media type is not accepted.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Rate limited. Wait Retry-After seconds and send the same request.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "BatchStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "cancelled" ] }, "DocumentStatus": { "type": "string", "enum": [ "awaiting_upload", "pending", "queued", "processing", "succeeded", "failed", "cancelled" ] }, "Metadata": { "type": "object", "description": "At most 20 string pairs of 500 characters each.", "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 20 }, "BatchCreate": { "type": "object", "properties": { "externalReference": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "BatchCounts": { "type": "object", "required": [ "total", "awaitingUpload", "pending", "queued", "processing", "succeeded", "failed", "cancelled" ], "properties": { "total": { "type": "integer" }, "awaitingUpload": { "type": "integer" }, "pending": { "type": "integer" }, "queued": { "type": "integer" }, "processing": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "cancelled": { "type": "integer" } } }, "Batch": { "type": "object", "required": [ "object", "id", "liveMode", "status", "counts", "createdAt" ], "properties": { "object": { "type": "string", "const": "data_engine.batch" }, "id": { "type": "string", "format": "uuid" }, "liveMode": { "type": "boolean", "description": "true for live clients, false for test clients." }, "status": { "$ref": "#/components/schemas/BatchStatus" }, "externalReference": { "type": [ "string", "null" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "counts": { "$ref": "#/components/schemas/BatchCounts" }, "cancellationReason": { "type": [ "string", "null" ], "enum": [ "requested", "expired", null ] }, "createdAt": { "type": "string", "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "BatchPage": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "PatientRef": { "type": "object", "required": [ "externalId" ], "properties": { "externalId": { "type": "string" } } }, "EncounterRef": { "type": "object", "properties": { "externalId": { "type": "string" }, "date": { "type": "string", "format": "date" } } }, "DocumentInput": { "type": "object", "required": [ "externalReference", "mediaType" ], "properties": { "externalReference": { "type": "string" }, "mediaType": { "type": "string" }, "content": { "type": "string", "description": "Inline text, at most 1 MiB." }, "filename": { "type": "string" }, "byteSize": { "type": "integer" }, "checksumSha256": { "type": "string", "description": "Base64 SHA-256 of the raw bytes." }, "patient": { "$ref": "#/components/schemas/PatientRef" }, "encounter": { "$ref": "#/components/schemas/EncounterRef" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "DocumentCreate": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DocumentInput" } } } }, "DocumentResult": { "type": "object", "properties": { "entityCount": { "type": "integer" }, "pageCount": { "type": "integer" }, "qualityStatus": { "type": "string", "description": "Lowercase. `ok`, `degraded`, or `translation_failed`." } } }, "DocumentError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "checksum_mismatch", "content_missing", "unsupported_content", "conversion_empty", "pipeline_failed", "not_processed" ] }, "message": { "type": "string" } } }, "Document": { "type": "object", "required": [ "object", "id", "liveMode", "batchId", "externalReference", "status", "mediaType", "createdAt" ], "properties": { "object": { "type": "string", "const": "data_engine.document" }, "id": { "type": "string", "format": "uuid" }, "liveMode": { "type": "boolean", "description": "true for live clients, false for test clients." }, "batchId": { "type": "string", "format": "uuid" }, "externalReference": { "type": "string" }, "status": { "$ref": "#/components/schemas/DocumentStatus" }, "mediaType": { "type": "string" }, "byteSize": { "type": [ "integer", "null" ] }, "patient": { "anyOf": [ { "$ref": "#/components/schemas/PatientRef" }, { "type": "null" } ] }, "encounter": { "anyOf": [ { "$ref": "#/components/schemas/EncounterRef" }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/DocumentResult" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/DocumentError" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DocumentPage": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "Code": { "type": "object", "required": [ "system", "code" ], "properties": { "system": { "type": "string", "description": "FHIR system URI." }, "code": { "type": "string" }, "display": { "type": "string" } } }, "Entity": { "type": "object", "required": [ "object", "id", "type", "text" ], "properties": { "object": { "type": "string", "const": "data_engine.entity" }, "id": { "type": "string" }, "type": { "type": "string" }, "text": { "type": "string", "description": "Text as written in the note." }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", null ], "description": "Extraction confidence." }, "polarity": { "type": "string", "description": "Lowercase, for example positive." }, "subject": { "type": "string" }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "attributes": { "type": "object", "additionalProperties": true, "description": "Details specific to the entity type, such as clinicalStatus." }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } } } }, "EntityPage": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "FhirBundle": { "type": "object", "description": "FHIR R4 Bundle.", "properties": { "resourceType": { "type": "string", "const": "Bundle" }, "type": { "type": "string" }, "entry": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "existingBatchId": { "type": "string", "format": "uuid" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "pointer", "code", "detail" ], "properties": { "pointer": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" } } } } } }, "TokenRequest": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "const": "client_credentials" }, "scope": { "type": "string", "description": "Space-delimited. Omitted means the client's allowed scopes." }, "client_assertion_type": { "type": "string", "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" }, "client_assertion": { "type": "string" } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } } }, "OAuthError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "Jwks": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }