# Contracko Parser API - **OpenAPI Version:** `3.1.1` - **API Version:** `0.4.0` Contracko Parser: separate bulk document processing using Parser credits, not needed to add contracts to your contract register. Define extraction schemas, process batches and retrieve output with API-key authentication. ## Changelog ### v1 0.4.0 (2026-11-09) Generated with oasdiff 1.33.0 from the public combined contract. Rollout-flagged operations remain excluded. Generation results now include `not_contract`, which completes without proposing or creating a type. Contract results can include `comparison`; start/status responses expose comparison and resolution metadata, `attempt` and `failureReason`. The new expand route adds selected missing fields while preserving existing definitions and contract values. Every generation operation, including retained status/result reads, requires `contract_type_ai_workflows`; disabled access returns HTTP 403. A recorded creation is Done, and discard preserves its Created history. #### API Changes ##### POST /contract-types/generations - :warning: added the new `de` enum value to the `targetLanguage` response property for the response status `200` - added the optional property `attempt` to the response with the `200` status - added the optional property `canUndo` to the response with the `200` status - added the optional property `comparison` to the response with the `200` status - added the optional property `comparisonVerdict` to the response with the `200` status - added the optional property `failureReason` to the response with the `200` status - added the optional property `improvementCount` to the response with the `200` status - added the optional property `matchedTypeAvailable` to the response with the `200` status - added the optional property `missingFieldCount` to the response with the `200` status - added the optional property `resolution` to the response with the `200` status - added the optional property `resolvedAt` to the response with the `200` status - added the optional property `trialRefunded` to the response with the `200` status - added the optional property `undoReason` to the response with the `200` status - added the optional property `verdict` to the response with the `200` status ##### GET /contract-types/generations/{runId} - :warning: added the new `de` enum value to the `targetLanguage` response property for the response status `200` - added the optional property `attempt` to the response with the `200` status - added the optional property `canUndo` to the response with the `200` status - added the optional property `comparison` to the response with the `200` status - added the optional property `comparisonVerdict` to the response with the `200` status - added the optional property `failureReason` to the response with the `200` status - added the optional property `improvementCount` to the response with the `200` status - added the optional property `matchedTypeAvailable` to the response with the `200` status - added the optional property `missingFieldCount` to the response with the `200` status - added the optional property `resolution` to the response with the `200` status - added the optional property `resolvedAt` to the response with the `200` status - added the optional property `trialRefunded` to the response with the `200` status - added the optional property `undoReason` to the response with the `200` status - added the optional property `verdict` to the response with the `200` status ##### GET /contract-types/generations/{runId}/draft - :warning: added `subschema #1, subschema #2, subschema #3` to the `result` response property `anyOf` list for the response status `200` - removed `subschema #1, subschema #2` from the `result` response property `anyOf` list for the response status `200` ##### POST /contract-types/generations/{runId}/expand - endpoint added ### v1 0.3.0 (2026-10-22) Authorization: `DELETE /contract-types/{id}` now requires `contract:write` (or legacy `contract:intake`) and active Contract Management API access. `parser:compute` alone can still list, get, create and update extraction schemas, but cannot delete them. Parsing-only keys receive HTTP 403 with the message "Deleting contract types requires a Contract Management (CLM) write key." Use a Contract Management (CLM) write key with active Contract Management API access to delete types. Enabled issuer and manage-type permission checks remain required. Request and response schemas are unchanged; oasdiff does not represent this authorization restriction (CTD-6002). ### v1 0.2.0 (2026-10-20) Generated with oasdiff 1.33.0 from the public combined contract. Rollout-flagged operations remain excluded. #### API Changes ##### POST /contracts/ingest - added the non-success response with the status `404` ### v1 0.1.1 (2026-10-20) Documentation: Removed empty navigation entries for pending-GA operations from the public API reference. Tags and groups now follow published operations and return automatically when those operations become public. Added descriptions for the contract type generation upload, start, status, and read-only result steps, including polling and review guidance. No public operations or request and response schemas changed. ### v1 0.1.0 (2026-10-18) Generated with oasdiff 1.33.0 from the public combined contract. Rollout-flagged operations remain excluded. Pre-launch release on `/api/v1`, with additive public parity work and compatibility corrections since the old 1.0.0 baseline. [ADR 0014](https://github.com/contracko/contracko/blob/staging/docs/adr/0014-integration-api-versioning.md) intentionally resets that unused baseline into the 0.x initial-development range. This history compares public specifications, not pilot runtime availability. Withdrawn operations can remain available to flagged workspaces or MCP; they are absent from the current public operation catalog. #### API Changes ##### GET /contract-types - added the new optional `query` request parameter `cursor` - added the new optional `query` request parameter `limit` - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - added the optional property `nextCursor` to the response with the `200` status ##### POST /contract-types - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `422` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /contract-types/generations - endpoint added ##### POST /contract-types/generations/upload-url - endpoint added ##### GET /contract-types/generations/{runId} - endpoint added ##### GET /contract-types/generations/{runId}/draft - endpoint added ##### DELETE /contract-types/{id} - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /contract-types/{id} - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### PATCH /contract-types/{id} - endpoint added ##### POST /contract-types/{id} - :warning: api removed without deprecation ##### GET /contracts - :warning: added `subschema #2, subschema #3` to the `items/items/filing` response property `anyOf` list for the response status `200` - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - removed `subschema #2, subschema #3` from the `items/items/filing` response property `anyOf` list for the response status `200` ##### PATCH /contracts - :warning: api removed without deprecation ##### POST /contracts/documents/search - :warning: api path removed without deprecation ##### DELETE /contracts/event-reminders - :warning: api path removed without deprecation ##### PATCH /contracts/event-reminders - :warning: api path removed without deprecation ##### POST /contracts/event-reminders - :warning: api path removed without deprecation ##### DELETE /contracts/events - :warning: api path removed without deprecation ##### PATCH /contracts/events - :warning: api path removed without deprecation ##### POST /contracts/events - :warning: api path removed without deprecation ##### POST /contracts/imports - :warning: api path removed without deprecation ##### GET /contracts/imports/{importId} - :warning: api path removed without deprecation ##### POST /contracts/ingest - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `402` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `413` status - added the optional property `data/refusalReason` to the response with the `415` status - added the optional property `data/refusalReason` to the response with the `422` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /contracts/upload-sessions - :warning: api path removed without deprecation ##### GET /contracts/upload-sessions/{uploadSessionId}/import - :warning: api path removed without deprecation ##### GET /contracts/{id} - :warning: added `subschema #2, subschema #3` to the `contract/filing` response property `anyOf` list for the response status `200` - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - removed `subschema #2, subschema #3` from the `contract/filing` response property `anyOf` list for the response status `200` ##### PATCH /contracts/{id} - :warning: api removed without deprecation ##### GET /contracts/{id}/access - :warning: added `subschema #2, subschema #3` to the `filing` response property `anyOf` list for the response status `200` - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - removed `subschema #2, subschema #3` from the `filing` response property `anyOf` list for the response status `200` ##### GET /contracts/{id}/analysis - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /contracts/{id}/comments - :warning: api path removed without deprecation ##### POST /contracts/{id}/comments - :warning: api path removed without deprecation ##### POST /contracts/{id}/documents - :warning: api path removed without deprecation ##### GET /contracts/{id}/documents/download - :warning: api path removed without deprecation ##### GET /contracts/{id}/documents/read - :warning: api path removed without deprecation ##### POST /contracts/{id}/documents/reprocess - :warning: api path removed without deprecation ##### GET /contracts/{id}/documents/reprocess/{runId} - :warning: api path removed without deprecation ##### GET /contracts/{id}/events - :warning: api path removed without deprecation ##### POST /contracts/{id}/move - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /contracts/{id}/reconciliations - :warning: api path removed without deprecation ##### GET /contracts/{id}/reconciliations/{runId} - :warning: api path removed without deprecation ##### POST /contracts/{id}/reconciliations/{runId}/apply - :warning: api path removed without deprecation ##### GET /folders - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /folders - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /folders/{id} - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /folders/{id}/access - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /folders/{id}/move - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /folders/{id}/rename - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /health - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - added the optional property `workspace/contractManagement` to the response with the `200` status ##### GET /parser/credits - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /parser/extractions - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /parser/jobs - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /parser/jobs - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /parser/jobs/{batchId} - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /parser/preflight - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /parser/reviews - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### POST /parser/upload-url - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `413` status - added the optional property `data/refusalReason` to the response with the `415` status - added the optional property `data/refusalReason` to the response with the `422` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /parties - added the new optional `query` request parameter `cursor` - added the new optional `query` request parameter `limit` - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status - added the optional property `nextCursor` to the response with the `200` status ##### POST /parties - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `409` status - added the optional property `data/refusalReason` to the response with the `422` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### GET /parties/{id} - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `404` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status ##### PATCH /parties/{id} - endpoint added ##### POST /parties/{id} - :warning: api removed without deprecation ##### POST /uploads/url - added the optional property `data/refusalReason` to the response with the `400` status - added the optional property `data/refusalReason` to the response with the `401` status - added the optional property `data/refusalReason` to the response with the `403` status - added the optional property `data/refusalReason` to the response with the `413` status - added the optional property `data/refusalReason` to the response with the `415` status - added the optional property `data/refusalReason` to the response with the `422` status - added the optional property `data/refusalReason` to the response with the `429` status - added the optional property `data/refusalReason` to the response with the `500` status #### Info - oasdiff detected breaking changes against the old `1.0.0` baseline. The reset to `0.1.0` is intentional under ADR 0014; breaking changes remain allowed on `/api/v1` before launch. Documentation: Clarified pre-launch version bumps, versions per path major, and the 6-month support window. ## Servers - **URL:** `/api/v1` - **Description:** Same-origin (current environment) - **URL:** `https://app.contracko.com/api/v1` - **Description:** Production ## Operations ### Check API key access - **Method:** `GET` - **Path:** `/health` - **Tags:** Authentication Verify that your API key is valid and return the workspace and access attached to it. #### Responses ##### Status: 200 API key verified. ###### Content-Type: application/json - **`keyId` (required)** `string` — Unique identifier for the API key - **`scopes` (required)** `array` — Access granted to the API key **Items:** `string` - **`status` (required)** `object` — Health status for the authenticated API key - **`timestamp` (required)** `string`, format: `date-time` — ISO-8601 timestamp generated by the API - **`keyName`** `object` — Label assigned to the API key - **`workspace`** `object` — Connected workspace summary, returned to MCP connections only - **`name` (required)** `object` — Connected workspace name - **`contractManagement`** `object` — Bounded Contract Management refusal and recovery hint; the credential remains valid - **`hint` (required)** `string` - **`refusalReason` (required)** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` - **`contracts`** `object` — Visible contract counts; present only with contract read access - **`examples` (required)** `integer` — Example contracts seeded for onboarding, titled "Example: ..." - **`real` (required)** `integer` — Contracts added by the workspace **Example:** ```json { "status": "ok", "timestamp": "", "keyId": "", "keyName": "", "scopes": [ "" ], "workspace": { "name": "", "contractManagement": { "refusalReason": "subscription_inactive", "hint": "" }, "contracts": { "real": 0, "examples": 0 } } } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### List contract types - **Method:** `GET` - **Path:** `/contract-types` - **Tags:** Contract Types Returns contract types scoped to the API key organisation. Use these types for contract intake or as parser extraction schemas referenced by categoryId. #### Responses ##### Status: 200 Contract types returned. ###### Content-Type: application/json - **`items` (required)** `array` — Contract types in this workspace **Items:** - **`createdAt` (required)** `string`, format: `date-time` - **`description` (required)** `object` - **`entityStatus` (required)** `object` — Read-only review state. AI-created types can be pending-review; any update clears it to null. - **`fields` (required)** `array` — Custom fields of this contract type **Items:** - **`categoryId` (required)** `string`, format: `uuid` - **`config` (required)** `object` - **`createdAt` (required)** `string`, format: `date-time` - **`defaultValue` (required)** `object` - **`description` (required)** `object` - **`displayOrder` (required)** `integer` - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`id` (required)** `string`, format: `uuid` - **`name` (required)** `string` - **`placeholder` (required)** `object` - **`required` (required)** `boolean` - **`updatedAt` (required)** `string`, format: `date-time` - **`id` (required)** `string`, format: `uuid` - **`isDefault` (required)** `boolean` - **`name` (required)** `string` - **`organisationId` (required)** `string` - **`source` (required)** `string`, possible values: `"manual", "template_adoption", "starting_template", "ai_generated"` - **`sourceTemplateId` (required)** `object` - **`sourceTemplateSlug` (required)** `object` - **`updatedAt` (required)** `string`, format: `date-time` - **`nextCursor`** `object` — Present only on paginated lists; null at the end. **Example:** ```json { "items": [ { "id": "", "name": "", "description": "", "organisationId": "", "isDefault": true, "source": "manual", "sourceTemplateId": "", "sourceTemplateSlug": "", "entityStatus": "pending-review", "createdAt": "", "updatedAt": "", "fields": [ { "id": "", "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": true, "config": "", "defaultValue": "", "displayOrder": -2147483648, "...": "[Additional Properties Truncated]" } ] } ], "nextCursor": "" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because the API key does not include the required access for this operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Create a contract type - **Method:** `POST` - **Path:** `/contract-types` - **Tags:** Contract Types Creates a contract type, optionally with custom fields, in the API key organisation. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Contract type name - **`description`** `object` — Optional description - **`fields`** `array`, default: `[]` — Optional custom fields to create with the contract type **Items:** - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`name` (required)** `string` - **`config`** `object`, default: `{}` — Type-specific settings: select and multi\_select need options (string array); number may set min, max and decimalPlaces. - **`defaultValue`** `object` - **`description`** `string` - **`options`** `array` **Items:** `string` - **`placeholder`** `string` - **`required`** `boolean`, default: `false` **Example:** ```json { "name": "", "description": "", "fields": [] } ``` #### Responses ##### Status: 200 Contract type created. ###### Content-Type: application/json - **`contractType` (required)** `object` — Contract type stored in Contracko - **`createdAt` (required)** `string`, format: `date-time` - **`description` (required)** `object` - **`entityStatus` (required)** `object` — Read-only review state. AI-created types can be pending-review; any update clears it to null. - **`fields` (required)** `array` — Custom fields of this contract type **Items:** - **`categoryId` (required)** `string`, format: `uuid` - **`config` (required)** `object` - **`createdAt` (required)** `string`, format: `date-time` - **`defaultValue` (required)** `object` - **`description` (required)** `object` - **`displayOrder` (required)** `integer` - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`id` (required)** `string`, format: `uuid` - **`name` (required)** `string` - **`placeholder` (required)** `object` - **`required` (required)** `boolean` - **`updatedAt` (required)** `string`, format: `date-time` - **`id` (required)** `string`, format: `uuid` - **`isDefault` (required)** `boolean` - **`name` (required)** `string` - **`organisationId` (required)** `string` - **`source` (required)** `string`, possible values: `"manual", "template_adoption", "starting_template", "ai_generated"` - **`sourceTemplateId` (required)** `object` - **`sourceTemplateSlug` (required)** `object` - **`updatedAt` (required)** `string`, format: `date-time` **Example:** ```json { "contractType": { "id": "", "name": "", "description": "", "organisationId": "", "isDefault": true, "source": "manual", "sourceTemplateId": "", "sourceTemplateSlug": "", "entityStatus": "pending-review", "createdAt": "", "updatedAt": "", "fields": [ { "id": "", "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": true, "config": "", "defaultValue": "", "displayOrder": -2147483648, "categoryId": "", "createdAt": "", "updatedAt": "" } ] } } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because the API key does not include the required access for this operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 409 A previous request with the same idempotency key is still being processed. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 422 Request is well-formed but contains values the API cannot process. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Get a contract type - **Method:** `GET` - **Path:** `/contract-types/{id}` - **Tags:** Contract Types Returns a single contract type scoped to the API key organisation. #### Responses ##### Status: 200 Contract type returned. ###### Content-Type: application/json - **`contractType` (required)** `object` — Contract type stored in Contracko - **`createdAt` (required)** `string`, format: `date-time` - **`description` (required)** `object` - **`entityStatus` (required)** `object` — Read-only review state. AI-created types can be pending-review; any update clears it to null. - **`fields` (required)** `array` — Custom fields of this contract type **Items:** - **`categoryId` (required)** `string`, format: `uuid` - **`config` (required)** `object` - **`createdAt` (required)** `string`, format: `date-time` - **`defaultValue` (required)** `object` - **`description` (required)** `object` - **`displayOrder` (required)** `integer` - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`id` (required)** `string`, format: `uuid` - **`name` (required)** `string` - **`placeholder` (required)** `object` - **`required` (required)** `boolean` - **`updatedAt` (required)** `string`, format: `date-time` - **`id` (required)** `string`, format: `uuid` - **`isDefault` (required)** `boolean` - **`name` (required)** `string` - **`organisationId` (required)** `string` - **`source` (required)** `string`, possible values: `"manual", "template_adoption", "starting_template", "ai_generated"` - **`sourceTemplateId` (required)** `object` - **`sourceTemplateSlug` (required)** `object` - **`updatedAt` (required)** `string`, format: `date-time` **Example:** ```json { "contractType": { "id": "", "name": "", "description": "", "organisationId": "", "isDefault": true, "source": "manual", "sourceTemplateId": "", "sourceTemplateSlug": "", "entityStatus": "pending-review", "createdAt": "", "updatedAt": "", "fields": [ { "id": "", "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": true, "config": "", "defaultValue": "", "displayOrder": -2147483648, "categoryId": "", "createdAt": "", "updatedAt": "" } ] } } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because the API key does not include the required access for this operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 404 The requested resource was not found. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Update a contract type - **Method:** `PATCH` - **Path:** `/contract-types/{id}` - **Tags:** Contract Types Updates a contract type. Include `fields` to reconcile the full custom-field set, or omit `fields` to leave custom fields unchanged. - `impact` reports whether the edit changed what AI extraction reads. Contracts already using this type keep their saved values and are never re-read by this call. #### Request Body ##### Content-Type: application/json - **`name` (required)** `string` — Contract type name - **`description`** `object` — Optional description - **`fields`** `array` — Optional full custom-field set to reconcile. Omit this field to leave existing custom fields unchanged. **Items:** - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`name` (required)** `string` - **`config`** `object`, default: `{}` — Type-specific settings: select and multi\_select need options (string array); number may set min, max and decimalPlaces. - **`defaultValue`** `object` - **`description`** `string` - **`id`** `string` - **`options`** `array` **Items:** `string` - **`placeholder`** `string` - **`required`** `boolean`, default: `false` **Example:** ```json { "name": "", "description": "", "fields": [ { "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": false, "config": {}, "options": [ "" ], "defaultValue": "", "id": "" } ] } ``` #### Responses ##### Status: 200 Contract type updated. ###### Content-Type: application/json - **`contractType` (required)** `object` — Contract type stored in Contracko - **`createdAt` (required)** `string`, format: `date-time` - **`description` (required)** `object` - **`entityStatus` (required)** `object` — Read-only review state. AI-created types can be pending-review; any update clears it to null. - **`fields` (required)** `array` — Custom fields of this contract type **Items:** - **`categoryId` (required)** `string`, format: `uuid` - **`config` (required)** `object` - **`createdAt` (required)** `string`, format: `date-time` - **`defaultValue` (required)** `object` - **`description` (required)** `object` - **`displayOrder` (required)** `integer` - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`id` (required)** `string`, format: `uuid` - **`name` (required)** `string` - **`placeholder` (required)** `object` - **`required` (required)** `boolean` - **`updatedAt` (required)** `string`, format: `date-time` - **`id` (required)** `string`, format: `uuid` - **`isDefault` (required)** `boolean` - **`name` (required)** `string` - **`organisationId` (required)** `string` - **`source` (required)** `string`, possible values: `"manual", "template_adoption", "starting_template", "ai_generated"` - **`sourceTemplateId` (required)** `object` - **`sourceTemplateSlug` (required)** `object` - **`updatedAt` (required)** `string`, format: `date-time` - **`impact` (required)** `object` — What this edit did, and did not, do to contracts already using this type - **`applicationRequiresExplicitApproval` (required)** `object` — Findings are only saved by an explicit apply call carrying an approval grant; grants are issued to clients that declare they can ask a person to approve the exact selection - **`changedFieldKeys` (required)** `array` — Information field keys added, removed, or redefined by this edit **Items:** `string` - **`existingContractsReprocessed` (required)** `object` — Editing a contract type never re-reads documents on existing contracts - **`existingContractValuesChanged` (required)** `object` — Editing a contract type never rewrites values already saved on contracts - **`extractionSchemaChanged` (required)** `boolean` — Whether this edit changed what AI extraction reads for this contract type - **`extractionSchemaFingerprint` (required)** `string` — Fingerprint of the extraction-relevant field definitions after this edit - **`previousExtractionSchemaFingerprint` (required)** `string` — Fingerprint of the extraction-relevant field definitions before this edit - **`recommendedNextAction` (required)** `string`, possible values: `"reprocess_relevant_documents", "none"` — Suggested follow-up for this edit - **`reprocessingRecommended` (required)** `boolean` — Whether re-reading affected documents would now produce different suggestions **Example:** ```json { "contractType": { "id": "", "name": "", "description": "", "organisationId": "", "isDefault": true, "source": "manual", "sourceTemplateId": "", "sourceTemplateSlug": "", "entityStatus": "pending-review", "createdAt": "", "updatedAt": "", "fields": [ { "id": "", "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": true, "config": "", "defaultValue": "", "displayOrder": -2147483648, "categoryId": "", "createdAt": "", "updatedAt": "" } ] }, "impact": { "extractionSchemaChanged": true, "changedFieldKeys": [ "" ], "existingContractsReprocessed": false, "existingContractValuesChanged": false, "reprocessingRecommended": true, "recommendedNextAction": "reprocess_relevant_documents", "applicationRequiresExplicitApproval": true, "previousExtractionSchemaFingerprint": "", "extractionSchemaFingerprint": "" } } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because the API key does not include the required access for this operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 404 The requested resource was not found. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 409 A previous request with the same idempotency key is still being processed. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 422 Request is well-formed but contains values the API cannot process. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Delete a contract type - **Method:** `DELETE` - **Path:** `/contract-types/{id}` - **Tags:** Contract Types Permanently deletes a non-default contract type and its custom-field definitions. - Requires `contract:write` (or the legacy `contract:intake` alias), Contract Management API access, and permission to manage contract types. `parser:compute` alone cannot delete contract types. - Contracts assigned to the deleted type are left unassigned. Existing custom-field values remain stored but are no longer associated with active field definitions. - Deleting a type after a parser batch is queued can cause that batch to fail because its requested extraction schema no longer exists. #### Responses ##### Status: 200 Contract type deleted. ###### Content-Type: application/json - **`contractType` (required)** `object` — Contract type stored in Contracko - **`createdAt` (required)** `string`, format: `date-time` - **`description` (required)** `object` - **`entityStatus` (required)** `object` — Read-only review state. AI-created types can be pending-review; any update clears it to null. - **`fields` (required)** `array` — Custom fields of this contract type **Items:** - **`categoryId` (required)** `string`, format: `uuid` - **`config` (required)** `object` - **`createdAt` (required)** `string`, format: `date-time` - **`defaultValue` (required)** `object` - **`description` (required)** `object` - **`displayOrder` (required)** `integer` - **`fieldKey` (required)** `string` - **`fieldType` (required)** `string`, possible values: `"text", "number", "date", "boolean", "currency", "percentage", "select", "multi_select"` - **`id` (required)** `string`, format: `uuid` - **`name` (required)** `string` - **`placeholder` (required)** `object` - **`required` (required)** `boolean` - **`updatedAt` (required)** `string`, format: `date-time` - **`id` (required)** `string`, format: `uuid` - **`isDefault` (required)** `boolean` - **`name` (required)** `string` - **`organisationId` (required)** `string` - **`source` (required)** `string`, possible values: `"manual", "template_adoption", "starting_template", "ai_generated"` - **`sourceTemplateId` (required)** `object` - **`sourceTemplateSlug` (required)** `object` - **`updatedAt` (required)** `string`, format: `date-time` **Example:** ```json { "contractType": { "id": "", "name": "", "description": "", "organisationId": "", "isDefault": true, "source": "manual", "sourceTemplateId": "", "sourceTemplateSlug": "", "entityStatus": "pending-review", "createdAt": "", "updatedAt": "", "fields": [ { "id": "", "name": "", "fieldKey": "", "description": "", "placeholder": "", "fieldType": "text", "required": true, "config": "", "defaultValue": "", "displayOrder": -2147483648, "categoryId": "", "createdAt": "", "updatedAt": "" } ] } } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because the API key does not include the required access for this operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 404 The requested resource was not found. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 409 A previous request with the same idempotency key is still being processed. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Check parser availability and estimated usage - **Method:** `POST` - **Path:** `/parser/preflight` - **Tags:** Parsing API Upload first, then supply every fileKey and the intended run options for an authoritative, 15-minute quote. Metadata-only requests return a provisional estimate. 1 credit per 10 pages. Adding AI review is an additional 1 credit per 10 pages. #### Request Body ##### Content-Type: application/json - **`files` (required)** `array` — Files to validate for parser processing **Items:** - **`fileName` (required)** `string` — Original file name including extension - **`fileSize` (required)** `integer` — File size in bytes - **`mimeType` (required)** `string` — RFC MIME type of the source file - **`fileKey`** `string` — Uploaded document reference. Supply every fileKey to receive an authoritative quote. - **`pageCountEstimate`** `integer` — Optional non-billing metadata. The server counts uploaded bytes for billing. - **`aiInferenceMode`** `string`, possible values: `"fast", "standard"` - **`categoryId`** `string`, format: `uuid` - **`deidentification`** `object` — Optional document-scoped protection policy. Omit for an unprotected result; pass an empty object for the contract-safe default. - **`consistencyScope`** `object`, default: `"document"` - **`overrides`** `array`, default: `[]` **Items:** - **`action` (required)** `object` - **`match` (required)** `object` - **`entityType`** `string`, possible values: `"person", "organisation", "email", "phone", "address", "identifier", "secret"` - **`fieldPath`** `string` - **`policyVersionId`** `object` - **`outputFormat`** `string`, possible values: `"json", "csv", "xlsx"` - **`outputLanguage`** `string`, possible values: `"source", "en", "nl", "de", "fr", "es", "it", "pt", "zh-Hans", "zh-Hant", "ja", "ko", "ar", "hi", "bn", "ta", "te", "mr", "ur", "id", "vi", "th", "pl", "sv", "da", "no", "fi", "tr", "ru", "uk", "ro", "cs", "hu", "el"` — Optional AI output language. Omit to use the workspace default; use source to preserve the document language. - **`outputTemplateId`** `string`, possible values: `"standard"` — Export layout template. standard keeps the default Contracko parser columns. - **`runKind`** `string`, possible values: `"extraction", "review"` — Request type. extraction performs structured extraction only; review adds AI analysis and costs extra credits. **Example:** ```json { "outputFormat": "json", "aiInferenceMode": "fast", "categoryId": "", "runKind": "extraction", "outputLanguage": "source", "outputTemplateId": "standard", "deidentification": { "policyVersionId": "contract-safe-v1", "consistencyScope": "document", "overrides": [] }, "files": [ { "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "pageCountEstimate": -9007199254740991, "fileKey": "" } ] } ``` #### Responses ##### Status: 200 Availability and estimated usage returned. ###### Content-Type: application/json - **`balance` (required)** `object` - **`allocated` (required)** `integer` — Allocated credits in the current billing cycle - **`remaining` (required)** `integer` — Credits available for new parser jobs - **`sourcePlanKey` (required)** `string` — Plan identifier associated with this usage window - **`used` (required)** `integer` — Credits consumed in the current billing cycle - **`breakdown` (required)** `object` — Credit breakdown by requested parser capability - **`analysis` (required)** `integer` — Additional credits for AI review analysis - **`extraction` (required)** `integer` — Credits for structured extraction - **`extractionTemplate` (required)** `integer` — Additional credits for extraction-template fields, currently included at no surcharge - **`outputLanguage` (required)** `integer` — Additional credits for output-language conversion, currently included at no surcharge - **`concurrency` (required)** `object` - **`active` (required)** `integer` — Parser batches currently in progress - **`max` (required)** `integer` — Maximum concurrent parser batches allowed - **`creditsNeeded` (required)** `integer` — Estimated credits required for this request - **`errors` (required)** `array` — Validation messages returned during preflight **Items:** `string` - **`fileCredits` (required)** `array` — Per-file credit breakdown **Items:** - **`analysisCredits` (required)** `integer` — Additional review credits for this file - **`baseCredits` (required)** `integer` — Base extraction credits for this file - **`credits` (required)** `integer` — Credits required for this file; exact cache hits cost zero - **`fileName` (required)** `string` — File name from the request - **`index` (required)** `integer` — Original file index in the request payload - **`pages`** `integer` — Authoritative server page count - **`limits` (required)** `object` - **`maxBatchBytes` (required)** `integer` — Maximum aggregate batch size - **`maxBatchFiles` (required)** `integer` — Maximum number of files per batch - **`maxFileBytes` (required)** `integer` — Maximum file size accepted per file - **`maxFilePages`** `integer` — Maximum authoritative pages per paid parser document - **`totalBytes` (required)** `integer` — Total request payload size in bytes - **`authoritative`** `boolean` — True only after server metering of uploaded documents - **`expiresAt`** `string`, format: `date-time` - **`pricingVersion`** `string` - **`quoteId`** `string`, format: `uuid` — Quote to pass when enqueueing these exact bytes and options **Example:** ```json { "quoteId": "", "expiresAt": "", "pricingVersion": "", "authoritative": true, "creditsNeeded": 0, "totalBytes": 0, "errors": [ "" ], "fileCredits": [ { "pages": -9007199254740991, "fileName": "", "credits": 0, "baseCredits": 0, "analysisCredits": 0, "index": 0 } ], "breakdown": { "extraction": 0, "analysis": 0, "outputLanguage": 0, "extractionTemplate": 0 }, "limits": { "maxFilePages": -9007199254740991, "maxFileBytes": -9007199254740991, "maxBatchBytes": -9007199254740991, "maxBatchFiles": -9007199254740991 }, "balance": { "allocated": 0, "used": 0, "remaining": 0, "sourcePlanKey": "" }, "concurrency": { "active": 0, "max": 0 } } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Create an upload URL - **Method:** `POST` - **Path:** `/parser/upload-url` - **Tags:** Parsing API Create a signed upload URL for a source file. Upload the file with HTTP PUT, then use the returned `fileKey` when you queue a batch. #### Request Body ##### Content-Type: application/json - **`fileName` (required)** `string` — Original file name including extension - **`fileSize` (required)** `integer` — File size in bytes - **`mimeType` (required)** `string` — RFC MIME type of the source file - **`pageCountEstimate`** `integer` — Optional non-billing metadata. The server counts uploaded bytes for billing. **Example:** ```json { "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "pageCountEstimate": -9007199254740991 } ``` #### Responses ##### Status: 200 Upload URL returned. ###### Content-Type: application/json - **`credits` (required)** `integer` — Estimated credits for this file - **`expiresIn` (required)** `integer` — Number of seconds until URL expiration - **`fileKey` (required)** `string` — File reference to include in POST /parser/jobs - **`uploadUrl` (required)** `string` — Single-use signed URL for file upload **Example:** ```json { "fileKey": "", "uploadUrl": "", "expiresIn": -9007199254740991, "credits": -9007199254740991 } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 413 Payload is too large for endpoint file-size or batch-size limits. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 415 File type is not supported for the selected operation. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 422 Request is well-formed but contains values the API cannot process. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Queue a parsing job - **Method:** `POST` - **Path:** `/parser/jobs` - **Tags:** Parsing API Queue uploaded documents with quoteId from POST /parser/preflight. The quote binds the exact bytes and run options. No separate cost confirmation is required at any credit amount. Missing or stale quotes return PARSER\_QUOTE\_REQUIRED with a fresh estimate. Poll GET /parser/jobs/{batchId} for results. #### Request Body ##### Content-Type: application/json - **`files` (required)** `array` — Files to include in the parser batch **Items:** - **`fileKey` (required)** `string` — Parser upload key returned by POST /parser/upload-url - **`fileName` (required)** `string` — Original file name including extension - **`fileSize` (required)** `integer` — File size in bytes - **`mimeType` (required)** `string` — RFC MIME type of the source file - **`pageCountEstimate`** `integer` — Optional non-billing metadata. The server counts uploaded bytes for billing. - **`aiInferenceMode`** `string`, possible values: `"fast", "standard"` — AI inference mode. Defaults to fast; choose standard for background work. - **`categoryId`** `string`, format: `uuid` — Optional extraction template / contract type UUID. When provided, custom fields from that template are extracted. - **`deidentification`** `object` — Optional document-scoped protection policy. The resolved version is applied before previews and exports are produced. - **`consistencyScope`** `object`, default: `"document"` - **`overrides`** `array`, default: `[]` **Items:** - **`action` (required)** `object` - **`match` (required)** `object` - **`entityType`** `string`, possible values: `"person", "organisation", "email", "phone", "address", "identifier", "secret"` - **`fieldPath`** `string` - **`policyVersionId`** `object` - **`outputFormat`** `string`, possible values: `"json", "csv", "xlsx"`, default: `"json"` — Requested export format for parser output. csv returns a ZIP bundle with one CSV per logical table; xlsx returns a multi-sheet workbook. - **`outputLanguage`** `string`, possible values: `"source", "en", "nl", "de", "fr", "es", "it", "pt", "zh-Hans", "zh-Hant", "ja", "ko", "ar", "hi", "bn", "ta", "te", "mr", "ur", "id", "vi", "th", "pl", "sv", "da", "no", "fi", "tr", "ru", "uk", "ro", "cs", "hu", "el"` — Optional AI output language. Omit to use the workspace default; use source to preserve the document language. - **`outputTemplateId`** `string`, possible values: `"standard"` — Export layout template. standard keeps the default Contracko parser columns. - **`quoteId`** `string`, format: `uuid` — Authoritative quote returned after upload by preflight. Required for a new parser submission. - **`runKind`** `string`, possible values: `"extraction", "review"` — Request type. extraction performs structured extraction only; review adds AI analysis and costs extra credits. **Example:** ```json { "quoteId": "", "aiInferenceMode": "fast", "outputFormat": "json", "runKind": "extraction", "outputLanguage": "source", "outputTemplateId": "standard", "categoryId": "", "deidentification": { "policyVersionId": "contract-safe-v1", "consistencyScope": "document", "overrides": [] }, "files": [ { "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "pageCountEstimate": -9007199254740991, "fileKey": "" } ] } ``` #### Responses ##### Status: 200 Batch queued. ###### Content-Type: application/json - **`batchId` (required)** `string` — Batch ID to use with GET /parser/jobs/{batchId} - **`creditsNeeded` (required)** `integer` — Credits reserved for this batch **Example:** ```json { "batchId": "", "creditsNeeded": 0 } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 412 A fresh parser quote or explicit confirmation of the batch cost is required. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### List parsing batches - **Method:** `GET` - **Path:** `/parser/jobs` - **Tags:** Parsing API List parser batches in reverse chronological order. - Query example: `/parser/jobs?limit=10&offset=0` #### Responses ##### Status: 200 Parser batches returned. ###### Content-Type: application/json - **`end` (required)** `integer` — 1-based inclusive index of last row in this page - **`hasMore` (required)** `boolean` — Whether additional pages are available - **`items` (required)** `array` — Parser batches in the requested page **Items:** - **`completedFiles` (required)** `integer` — Files completed so far - **`createdAt` (required)** `string`, format: `date-time` — ISO-8601 creation timestamp - **`creditCost` (required)** `object` — Parser credits billed to this Contracko Parser batch, when available - **`id` (required)** `string`, format: `uuid` — Batch UUID - **`outputFormat` (required)** `string` — Requested output format - **`retentionExpiresAt` (required)** `string`, format: `date-time` — ISO-8601 artifact retention expiration timestamp - **`status` (required)** `string` — Batch status - **`totalFiles` (required)** `integer` — Total files in the batch - **`metadata`** `object` — Additional batch metadata - **`limit` (required)** `integer` — Page size used in this response - **`offset` (required)** `integer` — Offset used in this response - **`page` (required)** `integer` — Current 1-based page index - **`pageCount` (required)** `integer` — Total number of pages - **`start` (required)** `integer` — 1-based inclusive index of first row in this page - **`total` (required)** `integer` — Total parser batches available for the organisation **Example:** ```json { "items": [ { "id": "", "status": "", "outputFormat": "", "creditCost": 0, "totalFiles": 0, "completedFiles": 0, "retentionExpiresAt": "", "createdAt": "", "metadata": null } ], "limit": 1, "offset": 0, "hasMore": true, "total": 0, "page": 1, "pageCount": 1, "start": 0, "end": 0 } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Queue an AI extraction - **Method:** `POST` - **Path:** `/parser/extractions` - **Tags:** Parsing API Queue an AI extraction batch from files you already uploaded with `POST /parser/upload-url`. Supports output language, extraction template, output format, and output template options. #### Request Body ##### Content-Type: application/json - **`files` (required)** `array` — Files to include in the parser batch **Items:** - **`fileKey` (required)** `string` — Parser upload key returned by POST /parser/upload-url - **`fileName` (required)** `string` — Original file name including extension - **`fileSize` (required)** `integer` — File size in bytes - **`mimeType` (required)** `string` — RFC MIME type of the source file - **`pageCountEstimate`** `integer` — Optional non-billing metadata. The server counts uploaded bytes for billing. - **`aiInferenceMode`** `string`, possible values: `"fast", "standard"` — AI inference mode. Defaults to fast; choose standard for background work. - **`categoryId`** `string`, format: `uuid` — Optional extraction template / contract type UUID. When provided, custom fields from that template are extracted. - **`deidentification`** `object` — Optional document-scoped protection policy. The resolved version is applied before previews and exports are produced. - **`consistencyScope`** `object`, default: `"document"` - **`overrides`** `array`, default: `[]` **Items:** - **`action` (required)** `object` - **`match` (required)** `object` - **`entityType`** `string`, possible values: `"person", "organisation", "email", "phone", "address", "identifier", "secret"` - **`fieldPath`** `string` - **`policyVersionId`** `object` - **`outputFormat`** `string`, possible values: `"json", "csv", "xlsx"`, default: `"json"` — Requested export format for parser output. csv returns a ZIP bundle with one CSV per logical table; xlsx returns a multi-sheet workbook. - **`outputLanguage`** `string`, possible values: `"source", "en", "nl", "de", "fr", "es", "it", "pt", "zh-Hans", "zh-Hant", "ja", "ko", "ar", "hi", "bn", "ta", "te", "mr", "ur", "id", "vi", "th", "pl", "sv", "da", "no", "fi", "tr", "ru", "uk", "ro", "cs", "hu", "el"` — Optional AI output language. Omit to use the workspace default; use source to preserve the document language. - **`outputTemplateId`** `string`, possible values: `"standard"` — Export layout template. standard keeps the default Contracko parser columns. - **`quoteId`** `string`, format: `uuid` — Authoritative quote returned after upload by preflight. Required for a new parser submission. - **`runKind`** `string`, possible values: `"extraction", "review"` — Request type. extraction performs structured extraction only; review adds AI analysis and costs extra credits. **Example:** ```json { "quoteId": "", "aiInferenceMode": "fast", "outputFormat": "json", "runKind": "extraction", "outputLanguage": "source", "outputTemplateId": "standard", "categoryId": "", "deidentification": { "policyVersionId": "contract-safe-v1", "consistencyScope": "document", "overrides": [] }, "files": [ { "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "pageCountEstimate": -9007199254740991, "fileKey": "" } ] } ``` #### Responses ##### Status: 200 Extraction batch queued. ###### Content-Type: application/json - **`batchId` (required)** `string` — Batch ID to use with GET /parser/jobs/{batchId} - **`creditsNeeded` (required)** `integer` — Credits reserved for this batch **Example:** ```json { "batchId": "", "creditsNeeded": 0 } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 412 A fresh parser quote or explicit confirmation of the batch cost is required. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Queue an AI contract review - **Method:** `POST` - **Path:** `/parser/reviews` - **Tags:** Parsing API Queue an AI contract review batch. This dedicated endpoint is the product-facing alias for extraction plus AI analysis/review output and uses the same polling flow as parser jobs. #### Request Body ##### Content-Type: application/json - **`files` (required)** `array` — Files to include in the parser batch **Items:** - **`fileKey` (required)** `string` — Parser upload key returned by POST /parser/upload-url - **`fileName` (required)** `string` — Original file name including extension - **`fileSize` (required)** `integer` — File size in bytes - **`mimeType` (required)** `string` — RFC MIME type of the source file - **`pageCountEstimate`** `integer` — Optional non-billing metadata. The server counts uploaded bytes for billing. - **`aiInferenceMode`** `string`, possible values: `"fast", "standard"` — AI inference mode. Defaults to fast; choose standard for background work. - **`categoryId`** `string`, format: `uuid` — Optional extraction template / contract type UUID. When provided, custom fields from that template are extracted. - **`deidentification`** `object` — Optional document-scoped protection policy. The resolved version is applied before previews and exports are produced. - **`consistencyScope`** `object`, default: `"document"` - **`overrides`** `array`, default: `[]` **Items:** - **`action` (required)** `object` - **`match` (required)** `object` - **`entityType`** `string`, possible values: `"person", "organisation", "email", "phone", "address", "identifier", "secret"` - **`fieldPath`** `string` - **`policyVersionId`** `object` - **`outputFormat`** `string`, possible values: `"json", "csv", "xlsx"`, default: `"json"` — Requested export format for parser output. csv returns a ZIP bundle with one CSV per logical table; xlsx returns a multi-sheet workbook. - **`outputLanguage`** `string`, possible values: `"source", "en", "nl", "de", "fr", "es", "it", "pt", "zh-Hans", "zh-Hant", "ja", "ko", "ar", "hi", "bn", "ta", "te", "mr", "ur", "id", "vi", "th", "pl", "sv", "da", "no", "fi", "tr", "ru", "uk", "ro", "cs", "hu", "el"` — Optional AI output language. Omit to use the workspace default; use source to preserve the document language. - **`outputTemplateId`** `string`, possible values: `"standard"` — Export layout template. standard keeps the default Contracko parser columns. - **`quoteId`** `string`, format: `uuid` — Authoritative quote returned after upload by preflight. Required for a new parser submission. - **`runKind`** `string`, possible values: `"extraction", "review"` — Request type. extraction performs structured extraction only; review adds AI analysis and costs extra credits. **Example:** ```json { "quoteId": "", "aiInferenceMode": "fast", "outputFormat": "json", "runKind": "extraction", "outputLanguage": "source", "outputTemplateId": "standard", "categoryId": "", "deidentification": { "policyVersionId": "contract-safe-v1", "consistencyScope": "document", "overrides": [] }, "files": [ { "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "pageCountEstimate": -9007199254740991, "fileKey": "" } ] } ``` #### Responses ##### Status: 200 Review batch queued. ###### Content-Type: application/json - **`batchId` (required)** `string` — Batch ID to use with GET /parser/jobs/{batchId} - **`creditsNeeded` (required)** `integer` — Credits reserved for this batch **Example:** ```json { "batchId": "", "creditsNeeded": 0 } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 412 A fresh parser quote or explicit confirmation of the batch cost is required. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Retrieve current usage - **Method:** `GET` - **Path:** `/parser/credits` - **Tags:** Parsing API Return current usage, remaining credits, and parser batch concurrency for the workspace. #### Responses ##### Status: 200 Current usage returned. ###### Content-Type: application/json - **`activeBatches` (required)** `integer` — Current number of active parser batches - **`allocated` (required)** `integer` — Allocated credits in the current billing cycle - **`isInTrial` (required)** `boolean` — Whether the parser subscription is currently in trial - **`maxConcurrency` (required)** `integer` — Maximum concurrent parser batches - **`planName` (required)** `string` — Human-readable name of the current parsing plan - **`refreshesAt` (required)** `object` — ISO-8601 refresh timestamp for credits - **`remaining` (required)** `integer` — Available credits for new parser work - **`sourcePlanKey` (required)** `string` — Plan identifier associated with this usage window - **`used` (required)** `integer` — Consumed credits in the current billing cycle **Example:** ```json { "allocated": 0, "used": 0, "remaining": 0, "sourcePlanKey": "", "refreshesAt": "", "planName": "", "maxConcurrency": 0, "activeBatches": 0, "isInTrial": true } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ### Retrieve batch results - **Method:** `GET` - **Path:** `/parser/jobs/{batchId}` - **Tags:** Parsing API Retrieve the current status, per-file extracted output preview, and download URL for a batch. #### Responses ##### Status: 200 Batch details returned. ###### Content-Type: application/json - **`batch` (required)** `object` - **`completedFiles` (required)** `integer` — Completed files in the batch - **`createdAt` (required)** `string`, format: `date-time` — ISO-8601 creation timestamp - **`creditCost` (required)** `object` — Total Parser credits charged for this Contracko Parser batch - **`downloadUrl` (required)** `object` — Signed URL to download the extracted output when the batch is completed - **`id` (required)** `string`, format: `uuid` — Batch UUID - **`outputFormat` (required)** `string` — Batch output format - **`retentionExpiresAt` (required)** `string`, format: `date-time` — ISO-8601 timestamp when artifacts expire - **`status` (required)** `string` — Batch processing status - **`totalFiles` (required)** `integer` — Total files in the batch - **`metadata`** `object` — Additional batch metadata - **`items` (required)** `array` — Per-file parser item status and previews **Items:** - **`creditCost` (required)** `object` — Parser credits charged for this Contracko Parser file - **`error` (required)** `object` — Error message when item processing fails - **`fileName` (required)** `string` — Original file name - **`fileSize` (required)** `object` — File size in bytes - **`id` (required)** `string`, format: `uuid` — Parser item UUID - **`mimeType` (required)** `string` — MIME type - **`status` (required)** `string` — Item processing status - **`outputPreview`** `object` — Contracko Parser bulk-processing output preview; does not add a contract to the CLM register - **`uploadRetentionExpiresAt`** `object` — ISO-8601 timestamp when uploaded source retention expires **Example:** ```json { "batch": { "id": "", "status": "", "outputFormat": "", "totalFiles": 0, "completedFiles": 0, "creditCost": 0, "retentionExpiresAt": "", "createdAt": "", "metadata": null, "downloadUrl": "" }, "items": [ { "id": "", "fileName": "", "mimeType": "", "fileSize": -9007199254740991, "creditCost": 0, "status": "", "error": "", "outputPreview": null, "uploadRetentionExpiresAt": "" } ] } ``` ##### Status: 400 Request validation failed (payload, query, or path format is invalid). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 401 Authentication failed (missing, invalid, revoked, or expired API key). ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 403 Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 404 The requested parser batch was not found. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 429 Retry later because the request rate limit was reached or too many parser batches are already running for this workspace. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ##### Status: 500 The server could not complete the request. ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. - **`message` (required)** `string` — Human-readable error message. - **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ``` ## Schemas ### ApiError - **Type:**`object` * **`code` (required)** `string` — Machine-readable ORPC/TRPC error code. * **`message` (required)** `string` — Human-readable error message. * **`data`** `object` — Optional structured metadata with endpoint-specific error context. - **`refusalReason`** `string`, possible values: `"subscription_inactive", "api_disabled", "not_member"` — Reviewed Contract Management or membership refusal reason. **Example:** ```json { "code": "", "message": "", "data": { "refusalReason": "subscription_inactive", "additionalProperty": "anything" }, "additionalProperty": "anything" } ```