Integration API endpoint reference
Every operation below is generated directly from the canonical OpenAPI contract
(packages/rule-line-sdk/openapi/openapi.json, source SHA-256 1926dd6e42f94f8e6e0682fc71b04937ef286aedf98c210b4c994e22e5aa4d4b) — the SAME
checked bytes the generated @one-unity/rule-line-sdk package is built from. A change to
either surface without regenerating the other is caught by docs:integration:check /
sdk:check, each comparing against its own copy of this one file's digest.
GET /datasets
Operation: listDatasets
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
limit | query | optional | integer |
cursor | query | optional | string |
ruleset | query | optional | string |
name | query | optional | string |
This operation returns results in cursor-paginated pages. Pass the response's nextCursor value back as the cursor query parameter to fetch the next page; treat nextCursor as an opaque string and never derive a page number from it.
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
items | required | array of object (see table below) |
nextCursor | required | string or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"currentSchemaHash": {
"anyOf": [
{
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
{
"type": "null"
}
]
},
"declared": {
"type": "boolean"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"latestVersion": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"kind": {
"enum": [
"full",
"delta",
"rebase"
],
"type": "string"
},
"rowCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"version",
"kind",
"rowCount",
"schemaHash",
"createdAt"
],
"type": "object"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"rulesetName": {
"type": "string"
},
"state": {
"enum": [
"declared",
"notDeclared",
"schemaChanged"
],
"type": "string"
},
"workingOrActiveVersionId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
],
"description": "The id of the ruleset version the console opens for this ruleset: the working draft when one exists, otherwise the newest activated version; null when no version of that name is visible. It changes as versions are created and activated, so do not use it as a stable key; rulesetName is the stable key."
}
},
"required": [
"id",
"rulesetName",
"workingOrActiveVersionId",
"name",
"declared",
"state",
"currentSchemaHash",
"latestVersion"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"nextCursor"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / The presented dataset cursor is invalid or has expired.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 400 | DATASET_CURSOR_INVALID |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
GET /datasets/{datasetId}
Operation: getDataset
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
datasetId | path | required | string (uuid) |
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
activeReads | required | object (see table below) or null |
currentSchemaHash | required | string or null |
declaration | required | any (unconstrained) or null |
declared | required | boolean |
id | required | string (uuid) |
latestVersion | required | object (see table below) or null |
name | required | string |
rulesetName | required | string |
schemaSource | required | any (unconstrained) or null |
state | required | "declared" | "notDeclared" | "schemaChanged" |
workingOrActiveVersionId | required | string (uuid) or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"activeReads": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"readsVersion": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
]
},
"rulesetVersionId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"rulesetVersionId",
"version",
"schemaHash",
"readsVersion"
],
"type": "object"
},
{
"type": "null"
}
]
},
"currentSchemaHash": {
"anyOf": [
{
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
{
"type": "null"
}
]
},
"declaration": {
"anyOf": [
{},
{
"type": "null"
}
]
},
"declared": {
"type": "boolean"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"latestVersion": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"kind": {
"enum": [
"full",
"delta",
"rebase"
],
"type": "string"
},
"rowCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"version",
"kind",
"rowCount",
"schemaHash",
"createdAt"
],
"type": "object"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"rulesetName": {
"type": "string"
},
"schemaSource": {
"anyOf": [
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"draftRevision": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"kind": {
"const": "draft",
"type": "string"
},
"rulesetVersionId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"rulesetVersionId",
"version",
"draftRevision"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "active",
"type": "string"
},
"rulesetVersionId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"rulesetVersionId",
"version"
],
"type": "object"
}
]
},
{
"type": "null"
}
]
},
"state": {
"enum": [
"declared",
"notDeclared",
"schemaChanged"
],
"type": "string"
},
"workingOrActiveVersionId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
],
"description": "The id of the ruleset version the console opens for this ruleset: the working draft when one exists, otherwise the newest activated version; null when no version of that name is visible. It changes as versions are created and activated, so do not use it as a stable key; rulesetName is the stable key."
}
},
"required": [
"id",
"rulesetName",
"workingOrActiveVersionId",
"name",
"declared",
"state",
"currentSchemaHash",
"latestVersion",
"declaration",
"schemaSource",
"activeReads"
],
"type": "object"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
GET /datasets/{datasetId}/versions
Operation: listDatasetVersions
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
datasetId | path | required | string (uuid) |
limit | query | optional | integer |
cursor | query | optional | string |
schemaHash | query | optional | string |
This operation returns results in cursor-paginated pages. Pass the response's nextCursor value back as the cursor query parameter to fetch the next page; treat nextCursor as an opaque string and never derive a page number from it.
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
items | required | array of object (see table below) |
nextCursor | required | string or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"actor": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"kind": {
"enum": [
"apiKey",
"user"
],
"type": "string"
}
},
"required": [
"kind",
"id"
],
"type": "object"
},
"baseVersion": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
]
},
"contentHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"createdAt": {
"type": "string"
},
"kind": {
"enum": [
"full",
"delta",
"rebase"
],
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"rowCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"rowsRemovedAt": {
"type": [
"string",
"null"
]
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"version",
"kind",
"baseVersion",
"rowCount",
"schemaHash",
"contentHash",
"actor",
"reason",
"createdAt",
"rowsRemovedAt"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"nextCursor"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / The presented dataset cursor is invalid or has expired.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 400 | DATASET_CURSOR_INVALID |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
POST /datasets/{datasetId}/versions
Operation: pushDatasetVersion
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
datasetId | path | required | string (uuid) |
Request body
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"expectedSchemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"mode": {
"const": "full",
"type": "string"
},
"reason": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"rows": {
"items": {},
"type": "array"
}
},
"required": [
"mode",
"rows"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"delete": {
"items": {},
"type": "array"
},
"expectedSchemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"mode": {
"const": "delta",
"type": "string"
},
"reason": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"upsert": {
"items": {},
"type": "array"
}
},
"required": [
"mode"
],
"type": "object"
}
]
}
Responses
201 — Success.
| Field | Presence | Type |
|---|---|---|
actor | required | object (see table below) |
baseVersion | required | integer or null |
contentHash | required | string |
createdAt | required | string |
datasetId | required | string (uuid) |
kind | required | "full" | "delta" | "rebase" |
reason | required | string or null |
rowCount | required | integer |
schemaHash | required | string |
version | required | integer |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"actor": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"kind": {
"enum": [
"apiKey",
"user"
],
"type": "string"
}
},
"required": [
"kind",
"id"
],
"type": "object"
},
"baseVersion": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
]
},
"contentHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"createdAt": {
"type": "string"
},
"datasetId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"kind": {
"enum": [
"full",
"delta",
"rebase"
],
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"rowCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"datasetId",
"version",
"kind",
"baseVersion",
"rowCount",
"schemaHash",
"contentHash",
"actor",
"reason",
"createdAt"
],
"type": "object"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
409 — The ruleset does not declare this dataset any more, so no data can be pushed to it. / The dataset declaration is not the one the push was prepared for; read the current declaration and push again. / A partial update cannot follow a change of the dataset declaration; push a full snapshot instead.
413 — The request body exceeds the permitted size for this route.
422 — The pushed rows do not conform to the dataset declaration, so nothing was written and no new version exists (all-or-nothing). The body carries the exact totals of rejected rows and problems and at most 100 structured diagnostics; a diagnostic names the row, the section, the key and the field path, and never a pushed value.
| Field | Presence | Type |
|---|---|---|
diagnostics | required | array of object (see table below) |
status | required | "422" (constant) |
title | required | string |
totalProblems | required | integer |
totalRejectedRows | required | integer |
type | required | string |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"diagnostics": {
"items": {
"additionalProperties": {},
"properties": {
"blocking": {
"type": "boolean"
},
"code": {
"type": "string"
},
"key": {
"type": [
"string",
"null"
]
},
"path": {
"type": "string"
},
"row": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"section": {
"enum": [
"rows",
"upsert",
"delete"
],
"type": "string"
},
"severity": {
"enum": [
"error",
"warning"
],
"type": "string"
}
},
"required": [
"code",
"severity",
"blocking",
"path",
"row",
"section",
"key"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"status": {
"const": 422,
"type": "number"
},
"title": {
"type": "string"
},
"totalProblems": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalRejectedRows": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"title",
"status",
"totalRejectedRows",
"totalProblems",
"diagnostics"
],
"type": "object"
}
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
| 409 | DATASET_NOT_DECLARED |
| 409 | DATASET_SCHEMA_CHANGED |
| 409 | DATASET_DELTA_SCHEMA_MISMATCH |
| 413 | REQUEST_BODY_TOO_LARGE |
GET /datasets/{datasetId}/versions/{version}/rows
Operation: listDatasetRows
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
datasetId | path | required | string (uuid) |
version | path | required | integer |
limit | query | optional | integer |
cursor | query | optional | string |
filter | query | optional | string or array of string |
This operation returns results in cursor-paginated pages. Pass the response's nextCursor value back as the cursor query parameter to fetch the next page; treat nextCursor as an opaque string and never derive a page number from it.
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
items | required | array of object (see table below) |
nextCursor | required | string or null |
offset | required | integer |
version | required | object (see table below) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"key": {
"type": "string"
},
"row": {
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"key",
"row"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"offset": {
"description": "Zero-based position of the first item of this page within the version's rows in the page's order; within the matches when the request is filtered. Display only: it is not accepted as a request parameter, paging is by cursor only.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"version": {
"additionalProperties": false,
"properties": {
"rowCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"rowsRemovedAt": {
"type": [
"string",
"null"
]
},
"schemaHash": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
"version": {
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"version",
"rowCount",
"schemaHash",
"rowsRemovedAt"
],
"type": "object"
}
},
"required": [
"version",
"items",
"nextCursor",
"offset"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / The presented dataset cursor is invalid or has expired. / A dataset row filter is malformed, or names a field that cannot be filtered on.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller. / The rows of this dataset version were removed by the retention policy.
504 — The dataset row query exceeded its time limit. Narrow the filters and retry.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 400 | DATASET_CURSOR_INVALID |
| 400 | DATASET_FILTER_INVALID |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
| 404 | DATASET_VERSION_REMOVED |
| 504 | DATASET_QUERY_TIMEOUT |
POST /documents
Operation: uploadDocument
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Request body
Content type: multipart/form-data.
| Field | Presence | Type |
|---|---|---|
file | required | any (unconstrained) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"file": {}
},
"required": [
"file"
],
"type": "object"
}
Responses
201 — Success.
| Field | Presence | Type |
|---|---|---|
createdAt | required | string |
digest | required | string |
documentId | required | string (uuid) |
mediaType | required | string |
sizeBytes | required | integer |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"digest": {
"type": "string"
},
"documentId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"mediaType": {
"type": "string"
},
"sizeBytes": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"documentId",
"mediaType",
"sizeBytes",
"digest",
"createdAt"
],
"type": "object"
}
400 — No file was presented in the upload request. / The upload request carried an unexpected form field. / A submitted document declares a media type the platform does not accept. / A submitted document's declared media type does not match its content. / A submitted document exceeds the per-document byte ceiling.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
413 — The request body exceeds the permitted size for this route.
500 — An unexpected error occurred while processing the request.
Known errors
DELETE /documents/{documentId}
Operation: retireDocument
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
documentId | path | required | string (uuid) |
Responses
204 — Success — no content.
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
POST /jobs
Operation: submitJob
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Request body
| Field | Presence | Type |
|---|---|---|
bypassAiCache | optional | boolean |
documents | optional | object — each key maps to array of object (see table below) or object (see table below) |
input | required | any (unconstrained) |
locale | optional | "de" | "en" |
rulesetId | required | string (uuid) |
test | required | boolean |
webhookDestinationId | optional | string (uuid) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"bypassAiCache": {
"description": "When true, every extract step of this run skips the AI result cache read and writes its fresh result as the newest cache entry for its key. Omitted means false. A fresh call is metered like any other call.",
"type": "boolean"
},
"documents": {
"additionalProperties": {
"items": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"inline": {
"additionalProperties": false,
"properties": {
"contentBase64": {
"minLength": 1,
"type": "string"
},
"mediaType": {
"minLength": 1,
"type": "string"
},
"originalFilename": {
"minLength": 1,
"type": "string"
}
},
"required": [
"contentBase64",
"mediaType"
],
"type": "object"
}
},
"required": [
"inline"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"documentId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"documentId"
],
"type": "object"
}
]
},
"type": "array"
},
"propertyNames": {
"pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$",
"type": "string"
},
"type": "object"
},
"input": {},
"locale": {
"description": "Language of check messages in this run. Use de for German or en for English. When omitted, the tenant default is frozen at submission. The poll response and result locale header report the chosen language.",
"enum": [
"de",
"en"
],
"type": "string"
},
"rulesetId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"test": {
"default": false,
"type": "boolean"
},
"webhookDestinationId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
}
},
"required": [
"rulesetId",
"input",
"test"
],
"type": "object"
}
Responses
202 — Success.
| Field | Presence | Type |
|---|---|---|
id | required | string (uuid) |
status | required | "queued" (constant) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"status": {
"const": "queued",
"type": "string"
}
},
"required": [
"id",
"status"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / A submitted document is not valid canonical base64. / A submitted document declares a media type the platform does not accept. / A submitted document's declared media type does not match its content. / A submitted document exceeds the per-document byte ceiling. / The request names more documents than the platform maximum. / The submitted documents exceed the aggregate byte ceiling.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
413 — The request body exceeds the permitted size for this route.
500 — An unexpected error occurred while processing the request.
Known errors
GET /jobs/{id}
Operation: pollJob
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
id | path | required | string (uuid) |
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
createdAt | required | string |
failedStepPath | required | string or null |
id | required | string (uuid) |
locale | required | "de" | "en" |
outcome | required | "succeeded" | "failed" or null |
payload | required | any (unconstrained) |
rawPurgedAt | required | string or null |
requestedRulesetVersionId | required | string (uuid) or null |
result | required | any (unconstrained) |
rulesetVersionId | required | string (uuid) |
softFallbacks | required | object (see table below) or null |
status | required | "queued" | "active" | "succeeded" | "failed" | "purged" |
terminatedAt | required | string or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"failedStepPath": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"locale": {
"description": "The run language frozen at submission.",
"enum": [
"de",
"en"
],
"type": "string"
},
"outcome": {
"anyOf": [
{
"enum": [
"succeeded",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"payload": {},
"rawPurgedAt": {
"type": [
"string",
"null"
]
},
"requestedRulesetVersionId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
],
"description": "The activated version handle named by the caller. Null for historical runs without this attribution."
},
"result": {},
"rulesetVersionId": {
"description": "The ruleset version actually executed, selected through the active version at submission.",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"softFallbacks": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"count"
],
"type": "object"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"queued",
"active",
"succeeded",
"failed",
"purged"
],
"type": "string"
},
"terminatedAt": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"rulesetVersionId",
"requestedRulesetVersionId",
"locale",
"status",
"outcome",
"createdAt",
"terminatedAt",
"failedStepPath",
"rawPurgedAt",
"payload",
"result",
"softFallbacks"
],
"type": "object"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
410 — The run's tenant erased it under the retention policy (GDPR erasure). The run itself is gone; this acknowledgement is rendered from the surviving tombstone and reports when the erasure happened.
| Field | Presence | Type |
|---|---|---|
erasedAt | required | string |
id | required | string (uuid) |
status | required | "erased" (constant) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"erasedAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"status": {
"const": "erased",
"type": "string"
}
},
"required": [
"id",
"status",
"erasedAt"
],
"type": "object"
}
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
GET /jobs/{id}/result
Operation: getJobResult
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
id | path | required | string (uuid) |
Responses
200 — Success — exact canonical bytes, never re-serialized.
Response headers:
| Header | Type |
|---|---|
Rule-Line-Result-Locale | "de" | "en" |
Rule-Line-Result-Sha256 | string |
Full JSON Schema
{
"format": "binary",
"type": "string"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
410 — The run's tenant erased it under the retention policy (GDPR erasure). The run itself is gone; this acknowledgement is rendered from the surviving tombstone and reports when the erasure happened.
| Field | Presence | Type |
|---|---|---|
erasedAt | required | string |
id | required | string (uuid) |
status | required | "erased" (constant) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"erasedAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"status": {
"const": "erased",
"type": "string"
}
},
"required": [
"id",
"status",
"erasedAt"
],
"type": "object"
}
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
GET /rulesets
Operation: listRulesets
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
name | query | optional | string |
status | query | optional | "draft" | "active" | "inactive" | "rejected" | "previously-activated" |
limit | query | optional | integer |
cursor | query | optional | string |
This operation returns results in cursor-paginated pages. Pass the response's nextCursor value back as the cursor query parameter to fetch the next page; treat nextCursor as an opaque string and never derive a page number from it.
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
items | required | array of object (see table below) |
nextCursor | required | string or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"activatedAt": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"draft",
"active",
"inactive",
"rejected",
"previously-activated"
],
"type": "string"
},
"version": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"name",
"version",
"status",
"createdAt",
"activatedAt"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"nextCursor"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / The presented ruleset-list cursor is invalid or has expired.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 400 | RULESET_CURSOR_INVALID |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
GET /runs
Operation: listRuns
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
rulesetId | query | optional | string (uuid) |
rulesetName | query | optional | string |
status | query | optional | "queued" | "active" | "succeeded" | "failed" | "purged" |
outcome | query | optional | "succeeded" | "failed" |
test | query | optional | boolean |
createdFrom | query | optional | string (date-time) |
createdTo | query | optional | string (date-time) |
deliveryStatus | query | optional | "due" | "claimed" | "succeeded" | "failed" | "exhausted" |
limit | query | optional | integer |
cursor | query | optional | string |
This operation returns results in cursor-paginated pages. Pass the response's nextCursor value back as the cursor query parameter to fetch the next page; treat nextCursor as an opaque string and never derive a page number from it.
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
items | required | array of object (see table below) |
nextCursor | required | string or null |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"deliveryStatus": {
"anyOf": [
{
"enum": [
"due",
"claimed",
"succeeded",
"failed",
"exhausted"
],
"type": "string"
},
{
"type": "null"
}
]
},
"outcome": {
"anyOf": [
{
"enum": [
"succeeded",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"rulesetId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"rulesetName": {
"type": [
"string",
"null"
]
},
"rulesetVersion": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"runId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"status": {
"enum": [
"queued",
"active",
"succeeded",
"failed",
"purged"
],
"type": "string"
},
"test": {
"type": "boolean"
}
},
"required": [
"runId",
"rulesetId",
"rulesetName",
"rulesetVersion",
"status",
"outcome",
"test",
"createdAt",
"deliveryStatus"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"nextCursor"
],
"type": "object"
}
400 — The request did not satisfy the required schema. / The presented run-history cursor is invalid or has expired.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 400 | RUN_CURSOR_INVALID |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
GET /runs/{runId}/delivery
Operation: getRunDelivery
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
runId | path | required | string (uuid) |
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
attempts | required | array of object (see table below) |
canRetry | required | boolean |
eventCreatedAt | required | string |
eventId | required | string (uuid) |
eventType | required | "run.succeeded" | "run.failed" |
hasDestination | required | boolean |
runCompletedAt | required | string |
runId | required | string (uuid) |
test | required | boolean |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"attempts": {
"items": {
"additionalProperties": false,
"properties": {
"attemptLabel": {
"type": "string"
},
"attemptNumber": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"cycleNumber": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"destinationUrlUsed": {
"type": [
"string",
"null"
]
},
"httpStatus": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"initiatedBy": {
"enum": [
"system",
"manual"
],
"type": "string"
},
"latencyMs": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"nextAttemptAt": {
"type": [
"string",
"null"
]
},
"requestPreview": {
"type": [
"string",
"null"
]
},
"responsePreview": {
"type": [
"string",
"null"
]
},
"secretVersionUsed": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
]
},
"sentAt": {
"type": "string"
},
"status": {
"enum": [
"due",
"claimed",
"succeeded",
"failed",
"exhausted"
],
"type": "string"
},
"transportError": {
"type": [
"string",
"null"
]
}
},
"required": [
"cycleNumber",
"attemptNumber",
"attemptLabel",
"initiatedBy",
"status",
"sentAt",
"destinationUrlUsed",
"secretVersionUsed",
"httpStatus",
"latencyMs",
"transportError",
"nextAttemptAt",
"requestPreview",
"responsePreview"
],
"type": "object"
},
"type": "array"
},
"canRetry": {
"type": "boolean"
},
"eventCreatedAt": {
"type": "string"
},
"eventId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"eventType": {
"enum": [
"run.succeeded",
"run.failed"
],
"type": "string"
},
"hasDestination": {
"type": "boolean"
},
"runCompletedAt": {
"type": "string"
},
"runId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"test": {
"type": "boolean"
}
},
"required": [
"runId",
"eventId",
"eventType",
"test",
"eventCreatedAt",
"runCompletedAt",
"hasDestination",
"canRetry",
"attempts"
],
"type": "object"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
GET /runs/{runId}/trace
Operation: getRunTrace
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
runId | path | required | string (uuid) |
after | query | optional | integer |
limit | query | optional | integer |
Responses
200 — Success.
| Field | Presence | Type |
|---|---|---|
events | required | array of any (unconstrained) |
failure | required | object (see table below) or null |
hasMore | required | boolean |
legacyOrdering | required | boolean |
nextAfter | required | integer or null |
outcome | required | "succeeded" | "failed" or null |
rulesetDocumentHash | required | string or null |
rulesetDraftRevisionId | required | string (uuid) or null |
rulesetId | required | string (uuid) |
rulesetRevision | required | integer or null |
status | required | "queued" | "active" | "succeeded" | "failed" | "purged" |
terminal | required | boolean |
test | required | boolean |
traceComplete | required | boolean |
unfinalizedCount | required | integer |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"events": {
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"iterationIndex": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"lifecycle": {
"const": "started",
"type": "string"
},
"occurrenceKey": {
"description": "The structural identity of the step occurrence, which resolves exactly one node of the ruleset revision the run pinned. For a sample try (a console test run of one extract step) it is the key of the sampled step in that pinned revision, for example compare/cases[0]/read, although the run executed a derived one-step ruleset; stepPath keeps the path the run executed. null only for an event written before the column existed.",
"type": [
"string",
"null"
]
},
"ordinal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"parentId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"const": "running",
"type": "string"
},
"stepPath": {
"type": "string"
}
},
"required": [
"id",
"parentId",
"stepPath",
"occurrenceKey",
"ordinal",
"iterationIndex",
"createdAt",
"lifecycle",
"status"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"inputs": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "inline",
"type": "string"
},
"value": {}
},
"required": [
"kind",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fieldPath": {
"type": "string"
},
"kind": {
"const": "reference",
"type": "string"
}
},
"required": [
"kind",
"fieldPath"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "unavailable",
"type": "string"
},
"purgedAt": {
"type": "string"
}
},
"required": [
"kind",
"purgedAt"
],
"type": "object"
}
]
},
"iterationIndex": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"lifecycle": {
"const": "finalized",
"type": "string"
},
"occurrenceKey": {
"description": "The structural identity of the step occurrence, which resolves exactly one node of the ruleset revision the run pinned. For a sample try (a console test run of one extract step) it is the key of the sampled step in that pinned revision, for example compare/cases[0]/read, although the run executed a derived one-step ruleset; stepPath keeps the path the run executed. null only for an event written before the column existed.",
"type": [
"string",
"null"
]
},
"ordinal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"outboundCalls": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "inline",
"type": "string"
},
"value": {}
},
"required": [
"kind",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fieldPath": {
"type": "string"
},
"kind": {
"const": "reference",
"type": "string"
}
},
"required": [
"kind",
"fieldPath"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "unavailable",
"type": "string"
},
"purgedAt": {
"type": "string"
}
},
"required": [
"kind",
"purgedAt"
],
"type": "object"
}
]
},
"outboundCallsMeta": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
]
},
"outputs": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "inline",
"type": "string"
},
"value": {}
},
"required": [
"kind",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fieldPath": {
"type": "string"
},
"kind": {
"const": "reference",
"type": "string"
}
},
"required": [
"kind",
"fieldPath"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "unavailable",
"type": "string"
},
"purgedAt": {
"type": "string"
}
},
"required": [
"kind",
"purgedAt"
],
"type": "object"
}
]
},
"parentId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"succeeded",
"failed"
],
"type": "string"
},
"stepPath": {
"type": "string"
}
},
"required": [
"id",
"parentId",
"stepPath",
"occurrenceKey",
"ordinal",
"iterationIndex",
"createdAt",
"lifecycle",
"status",
"inputs",
"outputs",
"outboundCalls",
"outboundCallsMeta"
],
"type": "object"
}
]
},
"type": "array"
},
"failure": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"code": {
"description": "The registered diagnostic code of the failure, an identifier from the published diagnostic catalog.",
"type": "string"
},
"detailCodes": {
"description": "Registered diagnostic codes that detail the failure. Empty once the raw-content purge has run, because the details they come from are purged.",
"items": {
"type": "string"
},
"type": "array"
},
"stepPath": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "The failing step's runtime path, the same value that step's trace events carry as stepPath. null for a run that failed before any step. Never an empty string (narrowed 2026-09-30: an empty stored path is published as null)."
}
},
"required": [
"code",
"stepPath",
"detailCodes"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Why the run failed, as identifiers only (never the engine message or any detail value). Present only when outcome is failed. null when the run did not fail, and also when the failure code is not in the published diagnostic catalog or could not be read: read outcome to tell the cases apart, because failure null does not mean the run succeeded."
},
"hasMore": {
"type": "boolean"
},
"legacyOrdering": {
"type": "boolean"
},
"nextAfter": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"outcome": {
"anyOf": [
{
"enum": [
"succeeded",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"rulesetDocumentHash": {
"type": [
"string",
"null"
]
},
"rulesetDraftRevisionId": {
"anyOf": [
{
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
{
"type": "null"
}
]
},
"rulesetId": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"rulesetRevision": {
"anyOf": [
{
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
{
"type": "null"
}
]
},
"status": {
"enum": [
"queued",
"active",
"succeeded",
"failed",
"purged"
],
"type": "string"
},
"terminal": {
"type": "boolean"
},
"test": {
"description": "Whether the run was a test run; a test run's calls may be served from the production cache.",
"type": "boolean"
},
"traceComplete": {
"type": "boolean"
},
"unfinalizedCount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"events",
"nextAfter",
"hasMore",
"status",
"outcome",
"terminal",
"traceComplete",
"unfinalizedCount",
"legacyOrdering",
"test",
"rulesetId",
"rulesetDraftRevisionId",
"rulesetRevision",
"rulesetDocumentHash",
"failure"
],
"type": "object"
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
410 — The run's tenant erased it under the retention policy (GDPR erasure). The run and its trace are gone; this acknowledgement is rendered from the surviving tombstone and reports when the erasure happened. It carries no decision metadata.
| Field | Presence | Type |
|---|---|---|
erasedAt | required | string |
id | required | string (uuid) |
status | required | "erased" (constant) |
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"erasedAt": {
"type": "string"
},
"id": {
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"status": {
"const": "erased",
"type": "string"
}
},
"required": [
"id",
"status",
"erasedAt"
],
"type": "object"
}
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
GET /runs/{runId}/trace/{traceId}/fields/{field}
Operation: getRunTraceField
Authentication: Requires a bearer token in the Authorization header (scheme: bearerAuth).
Parameters
| Name | Location | Presence | Type |
|---|---|---|---|
runId | path | required | string (uuid) |
traceId | path | required | string (uuid) |
field | path | required | string (uuid) |
Responses
200 — Success.
Full JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "inline",
"type": "string"
},
"value": {}
},
"required": [
"kind",
"value"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"fieldPath": {
"type": "string"
},
"kind": {
"const": "reference",
"type": "string"
}
},
"required": [
"kind",
"fieldPath"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "unavailable",
"type": "string"
},
"purgedAt": {
"type": "string"
}
},
"required": [
"kind",
"purgedAt"
],
"type": "object"
}
]
}
400 — The request did not satisfy the required schema.
401 — Authentication is required for this request.
403 — The caller is not permitted to perform this operation.
404 — The requested resource does not exist or is not visible to this caller.
413 — The request body exceeds the permitted size for this route.
Known errors
| Status | Code |
|---|---|
| 400 | VALIDATION_FAILED |
| 401 | AUTHENTICATION_REQUIRED |
| 403 | FORBIDDEN |
| 404 | NOT_FOUND |
| 413 | REQUEST_BODY_TOO_LARGE |