{ "openapi": "3.1.0", "info": { "title": "Aletheia API", "version": "0.0.0", "description": "Risk management infrastructure: subjects, workflow runs, cases, versioned definitions and collection flows. Every non-2xx response carries the `Error` schema: `{ error: { code, message, details?, requestId } }`.", "contact": { "email": "aletheia-dev@ajrd.net" } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "description": "Body of every non-2xx response. `requestId` is the value of the `x-request-id` response header: quote it when reporting a problem.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "requestId"], "properties": { "code": { "type": "string", "description": "Stable machine-readable code, e.g. `not_found`." }, "message": { "type": "string" }, "details": { "description": "Code-specific detail, e.g. `{ issues }` for `validation_error`." }, "requestId": { "type": "string" } } } } } } }, "paths": { "/activity": { "get": { "summary": "Recent decisions, breaches, publishes and approvals as sentences", "tags": ["home"], "description": "The newest audit events among `case.decided` and `case.sla.breached`, and with `definitions:read` the four `.published` actions and `definition.approval.requested`, `.approved`, `.rejected` and `.withdrawn`, each with a sentence (`text`) naming the actor from the reviewer directory and a console link (`href`). Payload values beyond the outcome, keys and versions are left out: the full events are on `GET /audit-events` with `audit:read`.", "parameters": [ { "schema": { "default": 5, "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "occurredAt": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["type", "id", "name"], "additionalProperties": false }, "text": { "type": "string" }, "href": { "type": ["string", "null"] }, "tone": { "type": "string", "enum": ["neutral", "alert"] } }, "required": ["id", "occurredAt", "action", "actor", "text", "href", "tone"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/app-callbacks": { "get": { "summary": "Vendor sessions awaiting or completed by webhook, newest first, with the total", "tags": ["apps"], "description": "`workflowRunId`, `status` and `appName` narrow the list; `total` counts every match, ignoring `limit` and `offset`. Each session names the `versionId` whose module handles its webhook, so an upgrade does not change how a pending session completes. Without `runs:context` every value of `output` is `[redacted]` (keys kept), and so is the `error` text: it can quote what the vendor answered about the subject.", "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "workflowRunId", "required": false }, { "schema": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "query", "name": "appName", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "action": { "type": "string" }, "externalId": { "type": "string" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "stepId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "output": { "anyOf": [ {}, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "appName", "versionId", "action", "externalId", "status", "createdAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/app-invocations": { "get": { "summary": "App invocations, newest first, filtered, with the total", "tags": ["apps"], "description": "`appName`, `workflowRunId` and `status` (repeated params) narrow the list; `from`/`to` are inclusive bounds on `invokedAt`. `total` counts the matches, ignoring `limit` and `offset`, and stops at 100,000: `totalIsEstimate` is `true` when it did. Each record names the `versionId` the call ran on and what it used at the runner (`usage`). Without `runs:context` every value of `input` and `output` is `[redacted]` (keys kept), and so is the `error` text: it can quote what the vendor answered about the subject.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "workflowRunId", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "query", "name": "appName", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["success", "error", "timeout", "pending"] } }, "in": "query", "name": "status", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "action": { "type": "string" }, "subjectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "input": {}, "output": { "anyOf": [ {}, { "type": "null" } ] }, "status": { "type": "string", "enum": ["success", "error", "timeout", "pending"] }, "error": { "type": ["string", "null"] }, "durationMs": { "type": "number", "minimum": 0 }, "invokedAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": ["string", "null"] }, "attempt": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "usage": { "anyOf": [ { "type": "object", "properties": { "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentReads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "logLines": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "appName", "versionId", "action", "input", "status", "durationMs", "invokedAt", "attempt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/app-invocations/{id}": { "get": { "summary": "One app invocation, with what was sent to and received from the vendor", "tags": ["apps"], "description": "Without `runs:context` every value of `input` and `output` is `[redacted]` (keys kept), and so is the `error` text. 404 when the invocation does not exist or belongs to another tenant.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "action": { "type": "string" }, "subjectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "input": {}, "output": { "anyOf": [ {}, { "type": "null" } ] }, "status": { "type": "string", "enum": ["success", "error", "timeout", "pending"] }, "error": { "type": ["string", "null"] }, "durationMs": { "type": "number", "minimum": 0 }, "invokedAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": ["string", "null"] }, "attempt": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "usage": { "anyOf": [ { "type": "object", "properties": { "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentReads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "logLines": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "appName", "versionId", "action", "input", "status", "durationMs", "invokedAt", "attempt" ], "additionalProperties": false } } } } } } }, "/approvals": { "get": { "summary": "Approval requests, filtered and paged, with the total", "tags": ["approvals"], "description": "`status=open` (the default) lists open requests, oldest first; `decided` the approved, rejected and withdrawn ones, newest decision first. `kind` narrows to one definition kind, `mine=true` to the caller's own requests and `stale=true` to requests made over a day ago. `total` counts every match, ignoring `limit` and `offset`.", "parameters": [ { "schema": { "default": "open", "type": "string", "enum": ["open", "decided"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "mine", "required": false }, { "schema": { "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "stale", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/approvals/{id}": { "get": { "summary": "One approval request with what deciding it needs", "tags": ["approvals"], "description": "The requested version in full; the published version and the diff from it (from the previous version when the requested one is published or nothing is); the latest completed backtest of a rule or workflow version; what the version names (`dependencies`) and the published definitions that name its key (`usage`); the users who may approve it, with why the requester may not under four-eyes; and the discussion, oldest first.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": {}, "publishedVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "diff": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "from": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": ["added", "removed", "changed", "moved"] }, "path": { "type": "string" }, "summary": { "type": "string", "minLength": 1 }, "before": {}, "after": {} }, "required": ["op", "path", "summary"], "additionalProperties": false } }, "delta": {}, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": ["added", "removed", "changed", "moved", "unchanged"] }, "from": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "before": { "type": ["string", "null"] }, "after": { "type": ["string", "null"] }, "changes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "op", "from", "to", "before", "after", "changes" ], "additionalProperties": false } } }, "required": ["kind", "key", "from", "to", "changes", "delta"], "additionalProperties": false }, { "type": "null" } ] }, "backtest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ruleKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "ruleVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workflowKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "workflowVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ruleSetKey": { "type": ["string", "null"] }, "sample": { "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": ["lastDays", "limit"], "additionalProperties": false }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["done", "total"], "additionalProperties": false }, "summary": { "anyOf": [ { "type": "object", "properties": { "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcomes": { "type": "object", "propertyNames": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": ["pass", "fail", "error", "skipped"] }, "wouldChange": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "overlap": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "sampleFailures": { "type": "array", "items": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "evaluationId", "subjectId", "evaluatedAt", "reasons" ], "additionalProperties": false } }, "decisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordedHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "versionHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "day", "evaluated", "recordedHits", "versionHits" ], "additionalProperties": false } }, "durationMs": { "type": "number", "minimum": 0 } }, "required": [ "evaluated", "outcomes", "wouldChange", "overlap", "sampleFailures", "durationMs" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "temporalWorkflowId": { "type": ["string", "null"] }, "requestedBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "sample", "status", "progress", "requestedBy", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["kind", "key"], "additionalProperties": false } }, "usage": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["kind", "key"], "additionalProperties": false } }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "eligible": { "type": "boolean" }, "reason": { "type": ["string", "null"] } }, "required": ["userId", "name", "eligible", "reason"], "additionalProperties": false } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "approvalId", "authorId", "body", "createdAt"], "additionalProperties": false } } }, "required": [ "approval", "definition", "publishedVersion", "diff", "backtest", "dependencies", "usage", "approvers", "comments" ], "additionalProperties": false } } } } } } }, "/approvals/{id}/comments": { "get": { "summary": "A request's discussion, oldest first", "tags": ["approvals"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "approvalId", "authorId", "body", "createdAt"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Add a message to a request's discussion; messages are never edited or removed", "tags": ["approvals"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": ["body"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "approvalId", "authorId", "body", "createdAt"], "additionalProperties": false } } } } } } }, "/apps": { "get": { "summary": "The catalogue: every app the tenant can install, with its install when it has one", "tags": ["apps"], "description": "One entry per name, by name: the platform's published apps and the tenant's own uploads whatever their status. `latest` is the newest published version, or the newest of any status when none is published; `versions` counts the versions the tenant sees. `install` carries the installed version unfolded, `missingSecrets` (the secrets that version names and the tenant has not stored) and `updateAvailable` (a newer published version of the same publisher exists). 503 `apps_unavailable` when the deployment runs no apps.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "latest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "versions": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "install": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" } }, "required": [ "id", "tenantId", "name", "versionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "missingSecrets", "updateAvailable" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["name", "publisher", "latest", "versions", "install"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/apps/approvals": { "get": { "summary": "Publish requests of the tenant's own app versions", "tags": ["apps"], "description": "The open requests (oldest first) by default, or the decided ones (newest first) with `open=false`, each with the version it would publish. An administrator other than the requester decides them with `POST /apps/:name/versions/:id/approve` or `/reject`.", "parameters": [ { "schema": { "default": "true", "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "open", "required": false }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false } }, "required": ["approval", "version"], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/apps/health": { "get": { "summary": "Per app, its calls of the last `windowMinutes` (5 to 1440, default 60)", "tags": ["apps"], "description": "Computed over the invocations of the window: `calls`, `failures` (`error` or `timeout`), `timeouts`, `p95Ms` (95th percentile of `durationMs` over the finished calls, `null` when every call is pending), `lastInvokedAt` and `lastErrorAt`. Apps without a call in the window are absent from `items`. No error text is returned: it can quote what the vendor answered about the subject. `circuits` lists the apps whose circuit breaker the workers last reported `open` or `half_open`, whatever the window; `blocked` the installs running on a module the operator blocked (`APP_BLOCKED_SHA256`): every call of them fails with `app_blocked`.", "parameters": [ { "schema": { "default": 60, "type": "integer", "minimum": 5, "maximum": 1440 }, "in": "query", "name": "windowMinutes", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "from": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "timeouts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p95Ms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "lastInvokedAt": { "type": "string", "format": "date-time" }, "lastErrorAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "appName", "calls", "failures", "timeouts", "p95Ms", "lastInvokedAt", "lastErrorAt" ], "additionalProperties": false } }, "circuits": { "type": "array", "items": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "since": { "type": "string", "format": "date-time" }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["appName", "state", "since", "failures"], "additionalProperties": false } }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["appName", "sha256"], "additionalProperties": false } } }, "required": ["windowMinutes", "from", "items", "circuits", "blocked"], "additionalProperties": false } } } } } } }, "/apps/uploads": { "post": { "summary": "Upload a module as a new version of one of the tenant’s apps", "tags": ["apps"], "description": "The body is the module itself (`application/wasm`, 32 MiB at most: 413 `payload_too_large` beyond). The API checks it is a module the platform runs (valid WebAssembly importing only the host interface, Extism's kernel and WASI without sockets and paths, exporting `manifest` and `invoke`: 400 `validation_error` with the `code` otherwise), asks the runner for its manifest (400 for a manifest the runner refuses, 502 `runner_` when the runner fails), writes the manifest's `memoryMiB` into the module as its memory maximum, stores it by its hash and records the version as `uploaded`: publish it with `POST /apps/:name/versions/:id/publish`. 409 `conflict` when the tenant already has that name and version. Audited as `app.uploaded`.", "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false } }, "required": ["version"], "additionalProperties": false } } } } } } }, "/apps/{name}": { "get": { "summary": "One app of the catalogue with every version the tenant sees, newest first", "tags": ["apps"], "description": "404 when neither the platform nor the tenant has a version of that name the tenant can see.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "latest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "versions": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "install": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" } }, "required": [ "id", "tenantId", "name", "versionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "missingSecrets", "updateAvailable" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["name", "publisher", "latest", "versions", "install"], "additionalProperties": false }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false } } }, "required": ["entry", "versions"], "additionalProperties": false } } } } } } }, "/apps/{name}/install": { "put": { "summary": "Install, configure or upgrade an app: one call for all three", "tags": ["apps"], "description": "Points the tenant's install of `name` at `versionId` (a published version the tenant sees; a withdrawn one keeps running where installed but cannot be newly installed), validates `config` against that version's schema (400 `validation_error` with the issues) and records the hosts the version declares as approved. `missingSecrets` lists the secrets the version names that have no value yet: `enabled: true` is refused with 409 `app_not_configured` while there are any, so an upgrade that adds a secret is \"store the secret, then upgrade\". 409 `conflict` for a version that is not published, 409 `app_blocked` for a module the operator blocked. Audited as `app.installed` the first time and `app.configured` after.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "enabled": { "default": true, "type": "boolean" }, "config": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["versionId"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" } }, "required": [ "id", "tenantId", "name", "versionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "missingSecrets", "updateAvailable" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Uninstall an app: the install and its secrets go, the history stays", "tags": ["apps"], "description": "409 `app_in_use` while runs wait on the app's callbacks, unless `force=true` fails those callbacks (each run ends its wait with `app_uninstalled`). Invocations and callbacks are kept. Audited as `app.uninstalled` with the callbacks failed. 404 without an install.", "parameters": [ { "schema": { "default": "false", "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "force", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/apps/{name}/secrets/{secret}": { "post": { "summary": "Store a secret of an installed app", "tags": ["apps"], "description": "Seals `value` with the deployment key (`SECRET_STORE_KEY`, AES-256-GCM) in the tenant's secret store, replacing the previous value of that name; the value is never returned or logged. The install's `missingSecrets` loses the name at once. Audited as `app.secret.stored` with the app and the secret name. 400 for a secret neither the installed version nor a published version of the app names (storing the secret a newer version adds before upgrading keeps the app enabled), 404 without an install, 503 `secret_store_unavailable` without a key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 8192 } }, "required": ["value"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "in": "path", "name": "secret", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "storedAt": { "type": "string", "format": "date-time" } }, "required": ["secret", "storedAt"], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a stored secret of an installed app", "tags": ["apps"], "description": "The install's `missingSecrets` gains the name again; calls of the app fail until a value is stored, and an enabled install is left enabled. Audited as `app.secret.revoked`. 404 without an install or a stored value of that name.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "in": "path", "name": "secret", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/apps/{name}/test": { "post": { "summary": "Call one action of an installed app once with the install's configuration, as a test", "tags": ["apps"], "description": "Runs the action on the installed version with the install's configuration, secrets and hosts, enabled or not, once: no retries, no circuit breaker, nothing recorded in `app_invocations`. The answer is what the call did: `success` with the validated output, `pending` with the vendor's external id (its webhook will find no run), `error` or `timeout` with what went wrong, plus `durationMs` and what the call `usage`d at the runner. Audited as `app.tested` with the action, status and duration, never the input or output. Without `runs:context` the output values and the error text are `[redacted]`. 400 for an action the version does not declare, 404 without an install, 409 `app_blocked` for a module the operator blocked, 503 `secret_store_unavailable` when a secret is stored and there is no key to open it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,99}$" }, "input": {} }, "required": ["action", "input"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["success", "pending", "error", "timeout"] }, "output": {}, "externalId": { "type": "string" }, "error": { "type": "string" }, "durationMs": { "type": "number", "minimum": 0 }, "usage": { "type": "object", "properties": { "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentReads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "logLines": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false } }, "required": ["status", "durationMs"], "additionalProperties": false } } } } } } }, "/apps/{name}/usage": { "get": { "summary": "The published definitions that call an app", "tags": ["apps"], "description": "The published workflows with a `call_app` step naming the app and the published `app` rules naming it, each with the actions it calls. An app in use is still uninstallable: its steps then fail with `unknown_app`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "definitions": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule"] }, "key": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": ["kind", "key", "version", "status", "actions"], "additionalProperties": false } } }, "required": ["name", "definitions"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions": { "get": { "summary": "The versions of an app the tenant sees, newest first", "tags": ["apps"], "description": "The platform's published versions (and the withdrawn ones the tenant's install still runs on) and the tenant's own uploads whatever their status, each with its manifest unfolded.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}": { "delete": { "summary": "Withdraw one of the tenant’s own versions", "tags": ["apps"], "description": "A withdrawn version keeps running where it is installed but cannot be newly installed; its module stays in storage. Audited as `app.withdrawn`. 404 for a platform version or another tenant’s.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/approve": { "post": { "summary": "Approve an open publish request and publish the version", "tags": ["apps"], "description": "With four-eyes on (`approvals.fourEyes`), never by its requester: 403 `four_eyes`. 404 without an open request. Audited as `app.approval.decided`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/publish": { "post": { "summary": "Publish an uploaded version, or request its approval", "tags": ["apps"], "description": "An uploaded version of the tenant's own. When the tenant requires approvals for apps (`approvals.required` with `requiredFor` unset or including `app`), a publish request is opened instead for another administrator to decide (202 with the `approval`; 409 `conflict` while one is open); otherwise the version is published at once (200, `approval` null). Audited as `app.approval.requested` or `app.published`. 404 for a platform version or another tenant's, 409 for a version already published or withdrawn.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval"], "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/reject": { "post": { "summary": "Reject an open publish request; the version stays uploaded", "tags": ["apps"], "description": "A rejected version can be requested again. 404 without an open request. Audited as `app.approval.decided`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "publisher": { "type": "string", "enum": ["platform", "tenant"] }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "version": { "type": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" }, "status": { "type": "string", "enum": ["uploaded", "published", "withdrawn"] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" }, "category": { "type": "string" }, "vendor": { "type": "string" }, "docsUrl": { "type": "string" }, "pricingNote": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "secrets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 253, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})$" } }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "memoryMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "handles": { "type": "object", "properties": { "webhook": { "default": false, "type": "boolean" }, "webhookExternalId": { "anyOf": [ { "type": "object", "properties": { "json": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~]|~[01])*)+$" } }, "required": ["json"], "additionalProperties": false }, { "type": "object", "properties": { "header": { "type": "string", "pattern": "^[a-z0-9!#$%&'*+.^_`|~-]{1,100}$" } }, "required": ["header"], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["query"], "additionalProperties": false } ] }, "handoff": { "type": "string", "enum": ["sumsub"] } }, "required": ["webhook"], "additionalProperties": false }, "actions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idempotent": { "type": "boolean" }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "backoffMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["maxAttempts", "backoffMs"], "additionalProperties": false }, "callbackTimeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "timeoutMs", "idempotent", "inputSchema", "outputSchema" ], "additionalProperties": false } }, "configSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "publisher", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt" ], "additionalProperties": false }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval"], "additionalProperties": false } } } } } } }, "/audit-events": { "get": { "summary": "Audit events, newest first; `action` is a prefix match, `from`/`to` are inclusive", "tags": ["audit"], "description": "`total` counts the matching events, ignoring `limit` and `offset`, and stops at 100,000: `totalIsEstimate` is `true` when it did. Without `runs:context` every value under a `context`, `data`, `details`, `input` or `output` key of the payload, at any depth, is `[redacted]` (keys kept), such as the rule result `details` of `workflow.rules.evaluated`; without `subjects:pii` personal data in the payload is masked. Ids, keys, versions, outcomes, counts and free text (reasons, comments) are returned as stored.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "actorId", "required": false }, { "schema": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "in": "query", "name": "actorType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "actorId": { "type": "string" }, "action": { "type": "string", "pattern": "^[a-z_]+(\\.[a-z_]+)+$" }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "payload": {}, "occurredAt": { "type": "string", "format": "date-time" }, "meta": { "anyOf": [ { "type": "object", "properties": { "requestId": { "type": "string" }, "route": { "type": "string" }, "ip": { "type": ["string", "null"] }, "userAgent": { "type": ["string", "null"] } }, "required": ["requestId", "route", "ip", "userAgent"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "actorType", "actorId", "action", "resourceType", "resourceId", "payload", "occurredAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/audit-events/count": { "get": { "summary": "How many events an export of these filters holds, and its size", "tags": ["audit"], "description": "`total` as on `GET /audit-events` (stopping at 100,000, `totalIsEstimate`) and `approxBytes`, the size of the CSV and JSON Lines export, estimated from the newest 200 matching events encoded as the export encodes them for the caller.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "actorId", "required": false }, { "schema": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "in": "query", "name": "actorType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalIsEstimate": { "type": "boolean" }, "approxBytes": { "type": "object", "properties": { "csv": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "jsonl": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["csv", "jsonl"], "additionalProperties": false } }, "required": ["total", "totalIsEstimate", "approxBytes"], "additionalProperties": false } } } } } } }, "/audit-events/export": { "get": { "summary": "Stream the filtered events oldest first as CSV or JSON Lines, ending with a manifest line (sha256 of everything before it, row count); the X-Export-Sha256 trailer carries the sha256 of the whole body, X-Export-Rows the row count", "tags": ["audit"], "description": "Payloads are presented for the caller as on `GET /audit-events`. The file is named `audit--.` unless `filename` names it (the extension is added). Each row carries `meta`, the request that wrote it (empty for rows the worker wrote).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "actorId", "required": false }, { "schema": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "in": "query", "name": "actorType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "default": "csv", "type": "string", "enum": ["csv", "jsonl"] }, "in": "query", "name": "format", "required": false }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" }, "in": "query", "name": "filename", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/audit-events/{id}": { "get": { "summary": "One audit event, its neighbours in the list and the records it concerns", "tags": ["audit"], "description": "Takes the list's filters: `neighbors` holds the events listed just above (`newerId`) and below (`olderId`) it under them, newest first. `related` names the case, decision, run and subject the event concerns, from its resource, the ids its payload holds and what those records point at. `meta`, the request that wrote it, shows its IP and user agent only to callers with `subjects:pii`. 404 when the event does not exist or belongs to another tenant. Without `runs:context` every value under a `context`, `data`, `details`, `input` or `output` key of the payload, at any depth, is `[redacted]` (keys kept), such as the rule result `details` of `workflow.rules.evaluated`; without `subjects:pii` personal data in the payload is masked. Ids, keys, versions, outcomes, counts and free text (reasons, comments) are returned as stored.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "actorId", "required": false }, { "schema": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "in": "query", "name": "actorType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceType", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "actorId": { "type": "string" }, "action": { "type": "string", "pattern": "^[a-z_]+(\\.[a-z_]+)+$" }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "payload": {}, "occurredAt": { "type": "string", "format": "date-time" }, "meta": { "anyOf": [ { "type": "object", "properties": { "requestId": { "type": "string" }, "route": { "type": "string" }, "ip": { "type": ["string", "null"] }, "userAgent": { "type": ["string", "null"] } }, "required": ["requestId", "route", "ip", "userAgent"], "additionalProperties": false }, { "type": "null" } ] }, "neighbors": { "type": "object", "properties": { "newerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "olderId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": ["newerId", "olderId"], "additionalProperties": false }, "related": { "type": "object", "properties": { "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "subjectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": ["caseId", "decisionId", "workflowRunId", "subjectId"], "additionalProperties": false } }, "required": [ "id", "tenantId", "actorType", "actorId", "action", "resourceType", "resourceId", "payload", "occurredAt", "neighbors", "related" ], "additionalProperties": false } } } } } } }, "/audit-export-runs/{id}/download": { "post": { "summary": "A short-lived link to a scheduled export's file", "tags": ["audit"], "description": "Five minutes long; audited as `audit.export.downloaded`. 409 for a run that failed or is still running.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "fileName": { "type": "string" } }, "required": ["url", "expiresAt", "fileName"], "additionalProperties": false } } } } } } }, "/audit-export-schedules": { "get": { "summary": "Scheduled audit exports", "tags": ["audit"], "description": "Oldest first, each with its newest run and `nextRunAt` from Temporal (`null` while paused or when Temporal is unreachable).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "cron": { "type": "string" }, "filter": { "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": [ "user", "service", "applicant", "system", "app", "workflow" ] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "format": { "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["running", "ok", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "windowFrom": { "type": "string", "format": "date-time" }, "windowTo": { "type": "string", "format": "date-time" }, "rows": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "type": ["string", "null"] }, "fileName": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "scheduleId", "status", "startedAt", "finishedAt", "windowFrom", "windowTo", "rows", "bytes", "sha256", "fileName", "error" ], "additionalProperties": false }, { "type": "null" } ] }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "cron", "filter", "format", "enabled", "createdBy", "createdAt", "updatedAt", "lastRun", "nextRunAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } }, "post": { "summary": "Schedule an audit export", "tags": ["audit"], "description": "Runs on `cron` (five fields, UTC) on a Temporal schedule, one run at a time. Each run exports the events matching `filter` from where the last successful run ended (the first: from the schedule's creation) to ten seconds before it starts, as `GET /audit-events/export` encodes them (manifest line included, payloads unredacted), and stores the file in the deployment's object storage under `audit-exports///`; download it through `POST /audit-export-runs/{id}/download`. A run is recorded and audited as `audit.exported` with the schedule; a failed one shows on Home and the next run covers its window again. A run larger than 256 MiB fails. At most 10 schedules. Audited as `audit_export_schedule.created`. 503 without object storage or Temporal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "cron": { "type": "string", "pattern": "^(\\S+\\s+){4}\\S+$" }, "filter": { "default": {}, "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } } }, "format": { "default": "csv", "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "default": true, "type": "boolean" } }, "required": ["name", "cron"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "cron": { "type": "string" }, "filter": { "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "format": { "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["running", "ok", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "windowFrom": { "type": "string", "format": "date-time" }, "windowTo": { "type": "string", "format": "date-time" }, "rows": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "type": ["string", "null"] }, "fileName": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "scheduleId", "status", "startedAt", "finishedAt", "windowFrom", "windowTo", "rows", "bytes", "sha256", "fileName", "error" ], "additionalProperties": false }, { "type": "null" } ] }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "cron", "filter", "format", "enabled", "createdBy", "createdAt", "updatedAt", "lastRun", "nextRunAt" ], "additionalProperties": false } } } } } } }, "/audit-export-schedules/{id}": { "get": { "summary": "One scheduled audit export", "tags": ["audit"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "cron": { "type": "string" }, "filter": { "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "format": { "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["running", "ok", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "windowFrom": { "type": "string", "format": "date-time" }, "windowTo": { "type": "string", "format": "date-time" }, "rows": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "type": ["string", "null"] }, "fileName": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "scheduleId", "status", "startedAt", "finishedAt", "windowFrom", "windowTo", "rows", "bytes", "sha256", "fileName", "error" ], "additionalProperties": false }, { "type": "null" } ] }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "cron", "filter", "format", "enabled", "createdBy", "createdAt", "updatedAt", "lastRun", "nextRunAt" ], "additionalProperties": false } } } } } }, "put": { "summary": "Change a scheduled audit export", "tags": ["audit"], "description": "Replaces its name, cron, filter, format and `enabled` (a disabled schedule is paused in Temporal). The next run still starts where the last successful one ended. Audited as `audit_export_schedule.updated`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "cron": { "type": "string", "pattern": "^(\\S+\\s+){4}\\S+$" }, "filter": { "default": {}, "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } } }, "format": { "default": "csv", "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "default": true, "type": "boolean" } }, "required": ["name", "cron"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "cron": { "type": "string" }, "filter": { "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "maxLength": 200 }, "actorId": { "type": "string", "minLength": 1 }, "actorType": { "type": "string", "enum": ["user", "service", "applicant", "system", "app", "workflow"] }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "format": { "type": "string", "enum": ["csv", "jsonl"] }, "enabled": { "type": "boolean" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRun": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["running", "ok", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "windowFrom": { "type": "string", "format": "date-time" }, "windowTo": { "type": "string", "format": "date-time" }, "rows": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "type": ["string", "null"] }, "fileName": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "scheduleId", "status", "startedAt", "finishedAt", "windowFrom", "windowTo", "rows", "bytes", "sha256", "fileName", "error" ], "additionalProperties": false }, { "type": "null" } ] }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "cron", "filter", "format", "enabled", "createdBy", "createdAt", "updatedAt", "lastRun", "nextRunAt" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a scheduled audit export", "tags": ["audit"], "description": "Deletes the Temporal schedule, the schedule and its runs; the files already written stay in object storage. Audited as `audit_export_schedule.deleted`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/audit-export-schedules/{id}/runs": { "get": { "summary": "The newest runs of a scheduled export", "tags": ["audit"], "description": "Newest first, at most 20: the window, the outcome, rows, size and digest.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["running", "ok", "failed"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "windowFrom": { "type": "string", "format": "date-time" }, "windowTo": { "type": "string", "format": "date-time" }, "rows": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sha256": { "type": ["string", "null"] }, "fileName": { "type": ["string", "null"] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "scheduleId", "status", "startedAt", "finishedAt", "windowFrom", "windowTo", "rows", "bytes", "sha256", "fileName", "error" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/audit-views": { "get": { "summary": "The caller's saved audit views, by name", "tags": ["audit"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "filters": { "type": "object", "properties": { "action": { "type": "string", "maxLength": 200 }, "actorType": { "type": "string", "maxLength": 40 }, "actorId": { "type": "string", "maxLength": 200 }, "resourceType": { "type": "string", "maxLength": 100 }, "resourceId": { "type": "string", "maxLength": 200 }, "from": { "type": "string", "maxLength": 40 }, "to": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "filters", "createdAt"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Save the trail filters under a name", "tags": ["audit"], "description": "`filters` are the trail's filter row as typed (strings, as in its URL). A view of the same name is replaced. Views belong to the caller alone; at most 50 each.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filters": { "type": "object", "properties": { "action": { "type": "string", "maxLength": 200 }, "actorType": { "type": "string", "maxLength": 40 }, "actorId": { "type": "string", "maxLength": 200 }, "resourceType": { "type": "string", "maxLength": 100 }, "resourceId": { "type": "string", "maxLength": 200 }, "from": { "type": "string", "maxLength": 40 }, "to": { "type": "string", "maxLength": 40 } } } }, "required": ["name", "filters"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "filters": { "type": "object", "properties": { "action": { "type": "string", "maxLength": 200 }, "actorType": { "type": "string", "maxLength": 40 }, "actorId": { "type": "string", "maxLength": 200 }, "resourceType": { "type": "string", "maxLength": 100 }, "resourceId": { "type": "string", "maxLength": 200 }, "from": { "type": "string", "maxLength": 40 }, "to": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "filters", "createdAt"], "additionalProperties": false } } } } } } }, "/audit-views/{id}": { "delete": { "summary": "Delete one of your saved views", "tags": ["audit"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/backtests": { "post": { "summary": "Start a backtest of a rule version (`ruleKey`) or a workflow version (`workflowKey`) over recent evaluation snapshots", "tags": ["backtests"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sample": { "default": { "lastDays": 30, "limit": 1000 }, "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } } }, "compareWithRuleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["ruleKey"] }, { "type": "object", "properties": { "workflowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sample": { "default": { "lastDays": 30, "limit": 1000 }, "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } } } }, "required": ["workflowKey"] } ] } } } }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ruleKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "ruleVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workflowKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "workflowVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ruleSetKey": { "type": ["string", "null"] }, "sample": { "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": ["lastDays", "limit"], "additionalProperties": false }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["done", "total"], "additionalProperties": false }, "summary": { "anyOf": [ { "type": "object", "properties": { "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcomes": { "type": "object", "propertyNames": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": ["pass", "fail", "error", "skipped"] }, "wouldChange": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "overlap": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "sampleFailures": { "type": "array", "items": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": ["evaluationId", "subjectId", "evaluatedAt", "reasons"], "additionalProperties": false } }, "decisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordedHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "versionHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["day", "evaluated", "recordedHits", "versionHits"], "additionalProperties": false } }, "durationMs": { "type": "number", "minimum": 0 } }, "required": [ "evaluated", "outcomes", "wouldChange", "overlap", "sampleFailures", "durationMs" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "temporalWorkflowId": { "type": ["string", "null"] }, "requestedBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "sample", "status", "progress", "requestedBy", "createdAt" ], "additionalProperties": false } } } } } }, "get": { "summary": "List backtests (newest first)", "tags": ["backtests"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ruleKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "ruleVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workflowKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "workflowVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ruleSetKey": { "type": ["string", "null"] }, "sample": { "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": ["lastDays", "limit"], "additionalProperties": false }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["done", "total"], "additionalProperties": false }, "summary": { "anyOf": [ { "type": "object", "properties": { "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcomes": { "type": "object", "propertyNames": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": ["pass", "fail", "error", "skipped"] }, "wouldChange": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "overlap": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "sampleFailures": { "type": "array", "items": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "evaluationId", "subjectId", "evaluatedAt", "reasons" ], "additionalProperties": false } }, "decisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordedHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "versionHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "day", "evaluated", "recordedHits", "versionHits" ], "additionalProperties": false } }, "durationMs": { "type": "number", "minimum": 0 } }, "required": [ "evaluated", "outcomes", "wouldChange", "overlap", "sampleFailures", "durationMs" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "temporalWorkflowId": { "type": ["string", "null"] }, "requestedBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "sample", "status", "progress", "requestedBy", "createdAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/backtests/{id}": { "get": { "summary": "Get a backtest with its progress and summary", "tags": ["backtests"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ruleKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "ruleVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "workflowKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] }, "workflowVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ruleSetKey": { "type": ["string", "null"] }, "sample": { "type": "object", "properties": { "lastDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 180 }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": ["lastDays", "limit"], "additionalProperties": false }, "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] }, "progress": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["done", "total"], "additionalProperties": false }, "summary": { "anyOf": [ { "type": "object", "properties": { "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcomes": { "type": "object", "propertyNames": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": ["pass", "fail", "error", "skipped"] }, "wouldChange": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "overlap": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "sampleFailures": { "type": "array", "items": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": ["evaluationId", "subjectId", "evaluatedAt", "reasons"], "additionalProperties": false } }, "decisions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordedHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "versionHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["day", "evaluated", "recordedHits", "versionHits"], "additionalProperties": false } }, "durationMs": { "type": "number", "minimum": 0 } }, "required": [ "evaluated", "outcomes", "wouldChange", "overlap", "sampleFailures", "durationMs" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "temporalWorkflowId": { "type": ["string", "null"] }, "requestedBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "sample", "status", "progress", "requestedBy", "createdAt" ], "additionalProperties": false } } } } } } }, "/case-queues": { "get": { "summary": "The case queues the caller sees, by position", "tags": ["cases"], "description": "The system queues (`systemKey` set; their name and filter are fixed) and the queues of the tenant with `visibility` `everyone`, `admins` (callers with `tenants:settings`) or `personal` (their creator). `claimNext` marks the queues \"Claim next\" draws from.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": { "type": "string", "format": "date-time" }, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "sort": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "type": "string", "enum": ["asc", "desc"] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdBy": { "type": "string", "minLength": 1 }, "systemKey": { "type": ["string", "null"] }, "visibility": { "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "type": "boolean" } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "name", "filter", "sort", "order", "position", "createdBy", "visibility", "claimNext" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Create a queue (names are unique per tenant)", "tags": ["cases"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "default": {}, "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": {}, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "sort": { "default": "createdAt", "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "default": "desc", "type": "string", "enum": ["asc", "desc"] }, "position": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "default": "everyone", "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "default": false, "type": "boolean" } }, "required": ["name"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": { "type": "string", "format": "date-time" }, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "sort": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "type": "string", "enum": ["asc", "desc"] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdBy": { "type": "string", "minLength": 1 }, "systemKey": { "type": ["string", "null"] }, "visibility": { "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "type": "boolean" } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "name", "filter", "sort", "order", "position", "createdBy", "visibility", "claimNext" ], "additionalProperties": false } } } } } } }, "/case-queues/counts": { "get": { "summary": "How many cases each queue the caller sees holds (`me` resolved)", "tags": ["cases"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "queueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["queueId", "count"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/case-queues/order": { "put": { "summary": "Reorder the queues", "tags": ["cases"], "description": "Gives each listed queue its index as position; queues the caller does not see are ignored and queues left out keep theirs. Returns the caller's queues in their new order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } }, "required": ["ids"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": { "type": "string", "format": "date-time" }, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "sort": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "type": "string", "enum": ["asc", "desc"] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdBy": { "type": "string", "minLength": 1 }, "systemKey": { "type": ["string", "null"] }, "visibility": { "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "type": "boolean" } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "name", "filter", "sort", "order", "position", "createdBy", "visibility", "claimNext" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/case-queues/preview": { "post": { "summary": "What a queue with this filter and sort would hold now", "tags": ["cases"], "description": "The number of matching cases and the first 5 in the queue's order, with their subjects; `assignee: me` is the caller.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "default": {}, "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": {}, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "sort": { "default": "createdAt", "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "default": "desc", "type": "string", "enum": ["asc", "desc"] } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] }, "subject": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "externalId": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "country": { "type": "string" }, "displayName": { "type": "string" } }, "required": ["id", "kind", "displayName"], "additionalProperties": false }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } } }, "required": ["total", "items"], "additionalProperties": false } } } } } } }, "/case-queues/{id}": { "put": { "summary": "Replace a queue's name, filter, sort, position, visibility and claim-next choice", "tags": ["cases"], "description": "A system queue keeps its name, filter and sort: only its position, visibility and claim-next choice change.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "default": {}, "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": {}, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "sort": { "default": "createdAt", "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "default": "desc", "type": "string", "enum": ["asc", "desc"] }, "position": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "default": "everyone", "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "default": false, "type": "boolean" } }, "required": ["name"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "filter": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": { "type": "string", "format": "date-time" }, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "sort": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "type": "string", "enum": ["asc", "desc"] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdBy": { "type": "string", "minLength": 1 }, "systemKey": { "type": ["string", "null"] }, "visibility": { "type": "string", "enum": ["everyone", "admins", "personal"] }, "claimNext": { "type": "boolean" } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "name", "filter", "sort", "order", "position", "createdBy", "visibility", "claimNext" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a queue (204, empty body); a system queue conflicts", "tags": ["cases"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/case-types": { "get": { "summary": "The case types in use: from published workflows and from open cases", "tags": ["cases"], "description": "Every `caseType` a published workflow's `create_case` step opens (with those workflows), and every type an open or in-review case has, with how many such cases there are. Sorted by type.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "workflows": { "type": "array", "items": { "type": "string" } }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["type", "workflows", "openCases"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/cases": { "get": { "summary": "List cases matching a filter (newest first by default), with the total", "tags": ["cases"], "description": "Array filters (`status`, `priority`, `slaState`) take repeated params. `assignee` is a reviewer id, `me` or `unassigned`; `queue` the routing label the run gave the case; `reasonCode` a code of the case's decision; `country` the subject's country as `GET /subjects?country=` reads it; `waiting=true` the cases waiting for the applicant (`false`: the others); `search` the start of the case id, or the subject as `GET /subjects?search=` finds it. `queueId` applies a queue the caller sees: its filter, with any filter given alongside replacing the queue's of the same name, and its sort unless one is given. Sort by `createdAt`, `dueAt` (undated last) or `priority`. `total` counts the matches, ignoring `limit` and `offset`, and stops at 100,000: `totalIsEstimate` is `true` when it did. `expand=subject` adds the subject of each case as `{ id, externalId, kind, country, displayName }`, read in one extra query; the name is not masked and nothing else from the subject data is returned. `expand=assignee` adds the assignee as `{ id, name, email }` from the reviewer directory (`name` `null` for someone it no longer lists; `null` when unassigned). The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "queueId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "in": "query", "name": "priority", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "assignee", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "in": "query", "name": "slaState", "required": false }, { "schema": {}, "in": "query", "name": "dueBefore", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "queue", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "reasonCode", "required": false }, { "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "in": "query", "name": "country", "required": false }, { "schema": { "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "waiting", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "in": "query", "name": "sort", "required": false }, { "schema": { "type": "string", "enum": ["asc", "desc"] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["subject", "assignee"] } }, "in": "query", "name": "expand", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] }, "subject": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "externalId": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "country": { "type": "string" }, "displayName": { "type": "string" } }, "required": ["id", "kind", "displayName"], "additionalProperties": false }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/cases/bulk": { "post": { "summary": "Assign, claim or close several cases, each exactly as its single-case route", "tags": ["cases"], "description": "Up to 100 ids, applied one at a time in order with the checks and audit events of `POST /cases/{id}/assign`, `/claim` and `/close`. `claim` also needs `cases:claim` and `close` needs `cases:decide`; an `assigneeId` outside the reviewer directory is a 404 for the whole request. A case that cannot change is listed in `failed` with its error code (`not_found`, `conflict`, ...) and the request still succeeds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "action": { "type": "string", "enum": ["assign", "claim", "close"] }, "assigneeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "reason": { "type": "string", "maxLength": 500 } }, "required": ["ids", "action"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "code", "message"], "additionalProperties": false } } }, "required": ["updated", "failed"], "additionalProperties": false } } } } } } }, "/cases/claim-next": { "post": { "summary": "Assign the caller the next free case of a queue or filter, atomically", "tags": ["cases"], "description": "Draws from a queue the caller sees (`queueId`: its filter and sort), from `filter` with `sort` and `order` (oldest first by default), or, with neither, from the queues marked `claimNext` in their order until one has a free case; always restricted to unassigned `open` and `in_review` cases. The first match that no concurrent claim holds (`FOR UPDATE SKIP LOCKED`) is assigned to the caller as `POST /cases/{id}/claim` does: `firstResponseAt` stamped once, `open` becomes `in_review`, audit `case.assigned`. 404 `nothing_to_claim` when no case is free. The case `context` is presented as on the other case routes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "queueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "filter": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": {}, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "sort": { "type": "string", "enum": ["createdAt", "dueAt", "priority"] }, "order": { "type": "string", "enum": ["asc", "desc"] } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "required": ["case"], "additionalProperties": false } } } } } } }, "/cases/counts": { "post": { "summary": "How many cases match each of several named filters", "tags": ["cases"], "description": "Up to 20 filters, each the `CaseFilter` that `GET /cases` and the queues take (`assignee: me` is the caller). One query per filter in one transaction; the names come back as the keys of `counts`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] } }, "priority": { "type": "array", "items": { "type": "string", "enum": ["low", "medium", "high", "critical"] } }, "assignee": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "slaState": { "type": "array", "items": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "dueBefore": {}, "queue": { "type": "string", "minLength": 1, "maxLength": 100 }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 60 }, "waiting": { "type": "boolean" }, "search": { "type": "string", "minLength": 1, "maxLength": 200 } } } } }, "required": ["filters"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": ["counts"], "additionalProperties": false } } } } } } }, "/cases/{id}": { "get": { "summary": "Case with its subject, run and the subject decisions", "tags": ["cases"], "description": "The subject is masked without `subjects:pii`; the run context and the rule result `details` of the decisions are `[redacted]` without `runs:context`. The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false }, "subject": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "riskScore": { "type": ["number", "null"] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "kind", "status", "data", "tags" ], "additionalProperties": false }, "run": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger" ], "additionalProperties": false }, { "type": "null" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "source": { "type": "string", "enum": ["automated", "manual"] }, "decidedBy": { "type": ["string", "null"] }, "ruleResults": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "subjectId", "outcome", "reasons", "source", "ruleResults", "createdAt" ], "additionalProperties": false } } }, "required": ["case", "subject", "run", "decisions"], "additionalProperties": false } } } } } } }, "/cases/{id}/assign": { "post": { "summary": "Assign a case to a reviewer from the directory, or unassign it with null", "tags": ["cases"], "description": "The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigneeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": ["assigneeId"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "required": ["case"], "additionalProperties": false } } } } } } }, "/cases/{id}/claim": { "post": { "summary": "Assign the case to the caller", "tags": ["cases"], "description": "The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "required": ["case"], "additionalProperties": false } } } } } } }, "/cases/{id}/close": { "post": { "summary": "Close a case; an undecided case is rejected first so its run can finish", "tags": ["cases"], "description": "A `decided` case closes directly. An `open` or `in_review` case first receives a manual `reject` decision with reason code `case_closed` (delivered to the waiting run like `/decide`), then closes. The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "required": ["case"], "additionalProperties": false } } } } } } }, "/cases/{id}/decide": { "post": { "summary": "Record a manual decision and resume the waiting run", "tags": ["cases"], "description": "A case assigned to someone else answers 409 `case_not_assigned` until the caller claims it; an unassigned case is assigned to the caller with the decision. When the tenant keeps a reason-code catalogue (`GET /reason-codes`), every reason must use one of its codes, allowed for the outcome, with a `note` where the code requires one (400 `validation_error` otherwise). The case `context` (the run context when the case opened) is `[redacted]` without `runs:context` and masked without `subjects:pii`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "reasons": { "default": [], "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"] } }, "note": { "type": "string" } }, "required": ["outcome"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false }, "decision": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "source": { "type": "string", "enum": ["automated", "manual"] }, "decidedBy": { "type": ["string", "null"] }, "ruleResults": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "subjectId", "outcome", "reasons", "source", "ruleResults", "createdAt" ], "additionalProperties": false } }, "required": ["case", "decision"], "additionalProperties": false } } } } } } }, "/cases/{id}/evidence": { "get": { "summary": "What a reviewer weighs on a case, in one response", "tags": ["cases"], "description": "`ruleHits`: the rules that failed on the newest evaluation of the case's run (shadow rules left out), or on the subject's newest decision without one, with its `riskScore`; `documents` (the subject's, `documents:read`), `vendorChecks` (the run's app calls, each with a `resultLabel`, `apps:read`) and `events` (the subject's newest 20, `events:read`), each `null` without its permission; `decisions` (the subject's newest 50). Payloads are redacted and masked as on their own routes.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleHits": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "riskScore": { "type": ["number", "null"] }, "documents": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "fieldKey": { "type": ["string", "null"] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": ["string", "null"] }, "storageKey": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "uploaded", "scanning", "clean", "infected", "rejected" ] }, "scan": { "anyOf": [ { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "signature": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" } }, "required": ["engine", "scannedAt"], "additionalProperties": false }, { "type": "null" } ] }, "rejectionReason": { "type": ["string", "null"] }, "rejectionCode": { "anyOf": [ { "type": "string", "enum": [ "empty", "too_large", "size_mismatch", "type_mismatch", "unsupported_type", "undecodable_image", "pdf_active_content", "object_missing" ] }, { "type": "null" } ] }, "thumbnailKey": { "type": ["string", "null"] }, "uploadedBy": { "type": "string", "minLength": 1 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "fileName", "contentType", "sizeBytes", "storageKey", "status", "uploadedBy" ], "additionalProperties": false } }, { "type": "null" } ] }, "vendorChecks": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "action": { "type": "string" }, "subjectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "input": {}, "output": { "anyOf": [ {}, { "type": "null" } ] }, "status": { "type": "string", "enum": ["success", "error", "timeout", "pending"] }, "error": { "type": ["string", "null"] }, "durationMs": { "type": "number", "minimum": 0 }, "invokedAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": ["string", "null"] }, "attempt": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "usage": { "anyOf": [ { "type": "object", "properties": { "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentReads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "logLines": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] }, "resultLabel": { "type": "string" } }, "required": [ "id", "tenantId", "appName", "versionId", "action", "input", "status", "durationMs", "invokedAt", "attempt", "resultLabel" ], "additionalProperties": false } }, { "type": "null" } ] }, "events": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "type": { "type": "string", "minLength": 1 }, "amount": { "type": ["number", "null"] }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "type": "string" }, "ip": { "type": ["string", "null"] }, "deviceId": { "type": ["string", "null"] }, "cardFingerprint": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "subjectId", "type", "occurredAt", "ingestedAt", "attributes", "idempotencyKey" ], "additionalProperties": false } }, { "type": "null" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "source": { "type": "string", "enum": ["automated", "manual"] }, "decidedBy": { "type": ["string", "null"] }, "ruleResults": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "subjectId", "outcome", "reasons", "source", "ruleResults", "createdAt" ], "additionalProperties": false } } }, "required": [ "ruleHits", "riskScore", "documents", "vendorChecks", "events", "decisions" ], "additionalProperties": false } } } } } } }, "/cases/{id}/notes": { "get": { "summary": "A case's notes, oldest first", "tags": ["cases"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "caseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "editedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "caseId", "authorId", "body" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Add a note to a case", "tags": ["cases"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": ["body"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "caseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "editedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "caseId", "authorId", "body" ], "additionalProperties": false } } } } } } }, "/cases/{id}/notes/{noteId}": { "patch": { "summary": "Edit a note (its author within 24 hours, or an admin)", "tags": ["cases"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": ["body"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "noteId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "caseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "authorId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "editedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "caseId", "authorId", "body" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a note (its author or an admin; 204, empty body)", "tags": ["cases"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "noteId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/cases/{id}/request-info": { "post": { "summary": "Ask the applicant for more information; the case and its run wait for the answer", "tags": ["cases"], "description": "The case's run gets the form it collected again, pre-filled with the answers (files included), as a follow-up linked to the case (`caseId`) that carries `message` as `requestMessage`. The case stays `in_review` with `infoRequestedAt` set and its SLA paused (`dueAt` empty). The answer repeats the run's checks after the form and hands the case back with what was left of the SLA; a request still unanswered at `expiresAt` (the flow's link lifetime) rejects the case with reason `info_not_provided`. Deciding or closing the case withdraws the request. `link` is the applicant's link to the follow-up, returned only here. 409 when the case is decided, closed or already waiting, when its run is not waiting on it, or when the run collected no form.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["message"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false }, "submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false }, "link": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["case", "submission", "link", "expiresAt"], "additionalProperties": false } } } } } } }, "/collection-field-types": { "get": { "summary": "Collection-flow field types with their option and value JSON Schemas", "tags": ["collection-flows"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "optionsSchema": {}, "valueSchema": {} }, "required": [ "type", "title", "description", "optionsSchema", "valueSchema" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/collection-flow-frame-ancestors": { "get": { "summary": "The origins that may frame a form link, for the collection terminal's web server", "tags": ["collection-submissions"], "description": "Public, and not rate limited: the web image asks it (nginx `auth_request`) on every `/flow/` page load and adds the answer to the page's `frame-ancestors`, after the deployment's `EMBED_ORIGINS`. `X-Submission-Id` names the submission. Always 204, with `X-Frame-Ancestors` holding the embed origins of its tenant (`embedOrigins` in `PUT /tenants/me/settings`), space-separated, and empty for an unknown or malformed id.", "responses": { "204": { "description": "Default Response" } } } }, "/collection-flow-preview": { "get": { "summary": "The flow version a preview link opens; the bearer is its preview token", "tags": ["collection-flows"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "name": { "type": "string" }, "definition": {}, "expiresAt": { "type": "string", "format": "date-time" }, "branding": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": "string", "format": "uri" }, "logoDarkUrl": { "type": "string", "format": "uri" }, "logoAlt": { "type": "string", "minLength": 1, "maxLength": 120 }, "primary": { "type": "string", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$" }, "radius": { "type": "number", "minimum": 0, "maximum": 24 }, "controlRadius": { "type": "number", "minimum": 0, "maximum": 24 }, "borderWidth": { "type": "number", "minimum": 1, "maximum": 2 }, "headingWeight": { "type": "integer", "minimum": 500, "maximum": 900 }, "font": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w\\s,'\"-]+$" }, "colorScheme": { "type": "string", "enum": ["light", "dark", "system"] }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "supportUrl": { "type": "string", "format": "uri" }, "privacyUrl": { "type": "string", "format": "uri" }, "termsUrl": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "locales": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" } } }, "required": [ "key", "version", "status", "name", "definition", "expiresAt", "branding", "locales" ], "additionalProperties": false } } } } } } }, "/collection-flows": { "get": { "summary": "Latest version of every collection flows key", "tags": ["collection-flows"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/collection-flows/validate": { "post": { "summary": "Validate a draft collection flow (upsert body) without saving it", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": ["error", "warning"] }, "path": { "type": "string" }, "stepId": { "type": "string" }, "fieldKey": { "type": "string" }, "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": ["severity", "path", "code", "message"], "additionalProperties": false } } }, "required": ["ok", "issues"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}": { "get": { "summary": "Latest version (any status)", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } } } } }, "put": { "summary": "Create a new draft version, with an optional change note", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"] } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type"] } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } } }, "required": ["id", "title", "fields"] } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } } } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } } } } } }, "required": ["entryStepId", "steps"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/diff": { "get": { "summary": "Changes between two versions; `to` defaults to the latest, `from` to the published version (else `to - 1`). A workflow diff adds `steps`, the steps one by one", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "from": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": ["added", "removed", "changed", "moved"] }, "path": { "type": "string" }, "summary": { "type": "string", "minLength": 1 }, "before": {}, "after": {} }, "required": ["op", "path", "summary"], "additionalProperties": false } }, "delta": {}, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": ["added", "removed", "changed", "moved", "unchanged"] }, "from": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "before": { "type": ["string", "null"] }, "after": { "type": ["string", "null"] }, "changes": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "op", "from", "to", "before", "after", "changes"], "additionalProperties": false } } }, "required": ["kind", "key", "from", "to", "changes", "delta"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/publish": { "post": { "summary": "Publish the newest draft; archives the previously published version. 409 `approval_required` when the tenant requires approvals", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions": { "get": { "summary": "Every version, newest first, with its latest approval request", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "name": { "type": "string" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "key", "version", "status", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}": { "patch": { "summary": "Save a draft version in place (the body PUT takes; an absent note keeps the stored one). 409 once it is no longer a draft", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"] } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type"] } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } } }, "required": ["id", "title", "fields"] } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } } } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } } } } } }, "required": ["entryStepId", "steps"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } } } } }, "get": { "summary": "One version in full (any status)", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": ["passport", "id_card", "proof_of_address", "selfie"] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}/approve": { "post": { "summary": "Approve an open request and publish the version; with four-eyes on, never by its requester", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}/preview": { "post": { "summary": "A link, valid 15 minutes, that opens this version in the collection terminal as a preview: nothing is saved", "tags": ["collection-flows"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["url", "expiresAt"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}/reject": { "post": { "summary": "Reject an open request; the version goes back to draft", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}/request-approval": { "post": { "summary": "Ask for a draft version to be approved and published (draft -> pending_approval)", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false } } } } } } }, "/collection-flows/{key}/versions/{version}/withdraw": { "post": { "summary": "Withdraw an open request; the version goes back to draft. By its requester, or an admin (`tenants:settings`)", "tags": ["collection-flows"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/collection-submissions": { "post": { "summary": "Start a submission of the published flow for a subject and get its link", "tags": ["collection-submissions"], "description": "The link opens the hosted collection flow (or the embed loader) with a signed token that lives `linkTtlSeconds` of the flow. Keep it as secret as the token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "required": ["flowKey", "subjectId"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false }, "link": { "type": ["string", "null"] } }, "required": ["submission", "link"], "additionalProperties": false } } } } } }, "get": { "summary": "Submissions, newest first, filtered, with the total", "tags": ["collection-submissions"], "description": "`subjectId`, `workflowRunId` and `status` (a repeated param) narrow the list; a submission started outside a workflow run has `workflowRunId: null`. `total` counts every match, ignoring `limit` and `offset`. Without `subjects:pii` the personal data in `data` is masked.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "workflowRunId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "caseId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] } }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}": { "get": { "summary": "Submission with the exact flow version it was started on", "tags": ["collection-submissions"], "description": "The applicant reads their own answers as entered. For every other caller without `subjects:pii` the personal data in `data` is masked.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false }, "flow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "status", "definition" ], "additionalProperties": false } }, "required": ["submission", "flow"], "additionalProperties": false } } } } } }, "patch": { "summary": "Save progress (data and current step)", "tags": ["collection-submissions"], "description": "A save replaces every answer. Send `If-Match` with the `updatedAt` you last read (or the `ETag` of the last response) to save only if nobody saved since, on another device or tab: otherwise 412 `stale_submission`, with the stored version in `details.updatedAt`. Without it the save always goes through.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": "string" } }, "required": ["data"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/appearance": { "get": { "summary": "The tenant's branding, as the collection terminal shows it to the applicant", "tags": ["collection-submissions"], "description": "`branding`: the tenant's `branding` settings over the deployment's defaults (the API's `COLLECTION_TERMINAL_*` variables); the tenant's name or logo replaces the default name and logo together, and either of its support contacts replaces both default ones. The terminal shows nothing but a loader until it has this. `locales` are the tenant's languages (`collection.locales`, English unset), the first being the one its flows are written in; a flow's `translations` add the others. `showDecision` (`COLLECTION_TERMINAL_SHOW_DECISION`) says whether applicants see the decision itself for flows that set no outcome visibility. Also answers a link that expired in the last 30 days.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": "string", "format": "uri" }, "logoDarkUrl": { "type": "string", "format": "uri" }, "logoAlt": { "type": "string", "minLength": 1, "maxLength": 120 }, "primary": { "type": "string", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$" }, "radius": { "type": "number", "minimum": 0, "maximum": 24 }, "controlRadius": { "type": "number", "minimum": 0, "maximum": 24 }, "borderWidth": { "type": "number", "minimum": 1, "maximum": 2 }, "headingWeight": { "type": "integer", "minimum": 500, "maximum": 900 }, "font": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w\\s,'\"-]+$" }, "colorScheme": { "type": "string", "enum": ["light", "dark", "system"] }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "supportUrl": { "type": "string", "format": "uri" }, "privacyUrl": { "type": "string", "format": "uri" }, "termsUrl": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "locales": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" } }, "showDecision": { "type": "boolean" } }, "required": ["branding", "locales", "showDecision"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/embed": { "get": { "summary": "Embed settings for a submission: allowed merchant origins and the flow name", "tags": ["collection-submissions"], "description": "Also answers a link that expired in the last 30 days, with `expired: true`, so the framed terminal can check its parent and tell it why it cannot go on; every other applicant route refuses an expired link, `appearance` aside.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "embedOrigins": { "type": "array", "items": { "type": "string", "pattern": "^https?:\\/\\/[a-z0-9.-]+(:\\d{1,5})?$" } }, "flowName": { "type": "string" }, "expired": { "type": "boolean" } }, "required": ["embedOrigins", "flowName", "expired"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/events": { "post": { "summary": "What the applicant's terminal reports: steps shown and uploads that failed", "tags": ["collection-submissions"], "description": "Applicants only. `events`, at most 50 (more are dropped): `{ type: 'step_viewed', stepId }` when a step is shown, `{ type: 'upload_failed', fieldKey, reason }` when a file does not make it (`reason`: the refusal or rejection code, or the API's error code). Ids and codes only, never answers; telemetry, so not audited. Events that do not parse or name a step or field the flow version does not have, and every event once the submission is no longer in progress, are dropped: the answer is 202 with how many were kept, whatever was sent, so a form never waits on or fails for it. They feed `GET /stats/flows/{key}/funnel`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": { "events": [] }, "description": "`{ events: [...] }`: see the description", "type": "object", "properties": { "events": { "type": "array", "items": {} } }, "required": ["events"] } } }, "description": "`{ events: [...] }`: see the description" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["accepted"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/handoff": { "get": { "summary": "Continue the applicant's pending identity check in the vendor's SDK", "tags": ["collection-submissions"], "description": "Applicants only. After the submit the run may wait for a vendor check the applicant takes part in (a liveness check, documents the vendor collects itself), started by an app whose manifest declares `handles.handoff` (the `sumsub` app: Sumsub's WebSDK). Mints a short-lived token for the vendor's SDK; ask again when it expires. `GET …/status` says `handoff: true` while there is one. 409 `handoff_unavailable` when nothing waits for the applicant: no such check is pending, or the vendor already has everything; 502 `handoff_failed` when the vendor does not answer. Audited as `collection.submission.handoff_started`, without the token.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sdk": { "type": "string", "enum": ["sumsub"] }, "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["sdk", "token", "expiresAt"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/link": { "post": { "summary": "Issue a new applicant link to a submission still in progress", "tags": ["collection-submissions"], "description": "For a lost or expired link. The link lives the flow's `linkTtlSeconds`, capped at `expiresAt` for a request for information; earlier links keep working until they expire. It carries a bearer token: send it to the applicant only. 409 once the submission is submitted, withdrawn or expired.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["link", "expiresAt"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/refresh": { "post": { "summary": "A fresh token for the applicant's live link, its expiry moved by the link lifetime", "tags": ["collection-submissions"], "description": "Applicants only, with a link that has not expired. The new token lives the flow's link lifetime from now, capped at `expiresAt` for a request for information; the old one keeps working until its own expiry. It is a bearer token: keep it where the old one was, never in a log. 409 once the submission is submitted, withdrawn or expired. Audited as `collection.submission.link_refreshed` with the new `expiresAt`.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["token", "expiresAt"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/resume-link": { "post": { "summary": "Ask the tenant for a new link, for an applicant whose link expired", "tags": ["collection-submissions"], "description": "Applicants only; answers a link that expired in the last 30 days too. Raises the webhook event `submission.link_requested` (ids only, never a link), on which the tenant's backend sends the applicant a fresh link (`POST /collection-submissions/{id}/link`). Asking again within 15 minutes answers the time of the first request and raises nothing. 409 `link_requests_unavailable` when no enabled webhook endpoint of the tenant takes the event, so the applicant should contact the tenant, and 409 once the submission is submitted, withdrawn or expired.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestedAt": { "type": "string", "format": "date-time" } }, "required": ["requestedAt"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/status": { "get": { "summary": "Applicant-readable progress of the run behind a submission", "tags": ["collection-submissions"], "description": "Once this submission is sent, `next` names the submission the same run now waits for (a request for information), with the reviewer's message; only the applicant gets its `link`. `handoff` is true while the run waits for a vendor check the applicant takes part in, which `GET …/handoff` continues in the vendor's SDK.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["id", "status", "submittedAt"], "additionalProperties": false }, "run": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "decision": { "anyOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["outcome"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["id", "status", "currentStepId", "decision"], "additionalProperties": false }, { "type": "null" } ] }, "next": { "anyOf": [ { "type": "object", "properties": { "submissionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "link": { "type": ["string", "null"] }, "message": { "type": ["string", "null"] } }, "required": ["submissionId", "link", "message"], "additionalProperties": false }, { "type": "null" } ] }, "handoff": { "type": "boolean" } }, "required": ["submission", "run", "next", "handoff"], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/submit": { "post": { "summary": "Validate against the flow, mark submitted and signal the waiting run", "tags": ["collection-submissions"], "description": "The answers, the audit event and the waiting run's signal commit together; the signal is sent at once and, when that fails (Temporal unreachable), the worker sends it until the run has it. A committed submit never answers an error.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false } } } } } } }, "/collection-submissions/{id}/withdraw": { "post": { "summary": "Withdraw a submission the applicant no longer needs to fill", "tags": ["collection-submissions"], "description": "Its link then opens a \"no longer needed\" screen. Withdrawing a request for information hands the case back to its reviewer with the rest of its SLA. 409 once the submission is submitted, withdrawn or expired, and for the form a workflow run is waiting for.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "flowDefinitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "flowVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["in_progress", "submitted", "withdrawn", "expired"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "currentStepId": { "type": ["string", "null"] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "requestMessage": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "flowDefinitionId", "flowKey", "flowVersion", "subjectId", "status", "data" ], "additionalProperties": false } } } } } } }, "/decisions": { "get": { "summary": "A subject's decisions, newest first, with the total", "tags": ["decisions"], "description": "`from`/`to` are inclusive bounds on `createdAt`; `limit` (default 50, max 500) and `offset` page the list and `total` counts every match. Without `runs:context` the `details` of each rule result are `[redacted]` (keys kept).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": true }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "source": { "type": "string", "enum": ["automated", "manual"] }, "decidedBy": { "type": ["string", "null"] }, "ruleResults": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "subjectId", "outcome", "reasons", "source", "ruleResults", "createdAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/definitions/export": { "get": { "summary": "Export the published versions of the named items as a policy pack (`keys=:`, repeated or comma-separated)", "tags": ["definitions"], "description": "Kinds: `rule`, `rule_set`, `workflow`, `collection_flow`, `list` (lists need `lists:read` and carry up to 10 000 rows). An item without a published version is a 404. App installs and their configuration are never exported.", "parameters": [ { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "keys", "required": true }, { "schema": { "default": "export", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "query", "name": "name", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "in": "query", "name": "version", "required": false }, { "schema": { "type": "string", "maxLength": 2000 }, "in": "query", "name": "description", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "type": "string", "maxLength": 2000 }, "definitions": { "type": "object", "properties": { "rules": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "default": "block", "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": "number" }, "enabled": { "default": true, "type": "boolean" }, "tags": { "default": [], "type": "array", "items": { "type": "string" } }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": [ "name", "type", "config", "severity", "enabled", "tags", "key" ], "additionalProperties": false } }, "ruleSets": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "useCase": { "default": "custom", "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "useCase", "definition", "key"], "additionalProperties": false } }, "workflows": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trigger": { "default": "manual", "type": "string", "enum": ["manual", "subject.created", "event"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": [ "id", "type", "caseType", "priority", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": [ "id", "type", "mode", "rulesKey", "manualDecisionKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "trigger", "definition", "key"], "additionalProperties": false } }, "collectionFlows": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } }, "additionalProperties": false }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type", "required"], "additionalProperties": false } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } } }, "required": ["id", "title", "fields"], "additionalProperties": false } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false } } }, "additionalProperties": false } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": ["entryStepId", "steps"], "additionalProperties": false }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "definition", "key"], "additionalProperties": false } }, "lists": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "default": true, "type": "boolean" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "rows": { "default": [], "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 512 }, "reason": { "type": "string", "maxLength": 1000 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["value"], "additionalProperties": false } } }, "required": ["name", "kind", "caseInsensitive", "key", "rows"], "additionalProperties": false } } }, "required": ["rules", "ruleSets", "workflows", "collectionFlows", "lists"], "additionalProperties": false } }, "required": ["name", "version", "definitions"], "additionalProperties": false } } } } } } }, "/definitions/import": { "post": { "summary": "Import a policy pack: every item is validated first, then lists are upserted and each definition gets a new draft version; `publish=true` also publishes (or requests approval)", "tags": ["definitions"], "description": "The pack is the body, or with `pack=` one of the starter packs `GET /definitions/packs` lists (then no body). Rejects the whole pack with 400 `validation_error` (`details.items` lists `{ kind, key, issues }`) before writing anything. Writes are sequential, not one transaction: a failure part-way leaves drafts behind, which never affect runs. `publish=true` needs `definitions:publish` too and follows the tenant approval settings: with approvals required the versions end `pending_approval` with an open request each.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "type": "string", "maxLength": 2000 }, "definitions": { "type": "object", "properties": { "rules": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "default": "block", "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": "number" }, "enabled": { "default": true, "type": "boolean" }, "tags": { "default": [], "type": "array", "items": { "type": "string" } }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "type", "config", "key"] } }, "ruleSets": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "useCase": { "default": "custom", "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey"] } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } } }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"] } } }, "required": ["mode", "bands"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode"] } ] } }, "required": ["rules", "policy"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "definition", "key"] } }, "workflows": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trigger": { "default": "manual", "type": "string", "enum": ["manual", "subject.created", "event"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } } } }, "required": ["id", "type", "app", "action", "outputKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"] } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"] } } } } }, "required": ["entryStepId", "steps"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "definition", "key"] } }, "collectionFlows": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "email", "number", "select", "date", "boolean", "file" ] }, "required": { "default": false, "type": "boolean" }, "placeholder": { "type": "string" }, "help": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": ["value", "label"] } }, "validation": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "pattern": { "type": "string" } } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "visibleWhen": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "multiple": { "type": "boolean" }, "maxFiles": { "type": "integer", "minimum": 2, "maximum": 10 }, "capture": { "type": "string", "enum": ["camera", "upload", "both"] }, "documentKind": { "type": "string", "enum": [ "passport", "id_card", "proof_of_address", "selfie" ] }, "autocomplete": { "type": "string", "enum": [ "off", "name", "honorific-prefix", "given-name", "additional-name", "family-name", "honorific-suffix", "nickname", "organization", "organization-title", "street-address", "address-line1", "address-line2", "address-line3", "address-level1", "address-level2", "address-level3", "address-level4", "postal-code", "country", "country-name", "email", "tel", "tel-country-code", "tel-national", "url", "bday", "sex", "language", "one-time-code" ] }, "inputMode": { "type": "string", "enum": [ "text", "numeric", "decimal", "tel", "email", "url", "search" ] } }, "required": ["key", "label", "type"] } }, "next": { "type": "string" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } } }, "required": ["id", "title", "fields"] } }, "linkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["neutral", "progress", "decision"] }, "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "translations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "steps": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "help": { "type": "string" }, "placeholder": { "type": "string" }, "unit": { "type": "string", "minLength": 1, "maxLength": 12 }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1 } }, "messages": { "type": "object", "properties": { "required": { "type": "string", "minLength": 1, "maxLength": 200 }, "invalid": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } } } }, "presentation": { "type": "object", "properties": { "intro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "outro": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } }, "outcome": { "type": "object", "properties": { "review": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "approved": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "rejected": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } } } } } }, "required": ["entryStepId", "steps"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "required": ["name", "definition", "key"] } }, "lists": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "default": true, "type": "boolean" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "rows": { "default": [], "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 512 }, "reason": { "type": "string", "maxLength": 1000 }, "expiresAt": {} }, "required": ["value"] } } }, "required": ["name", "kind", "key"] } } } } }, "required": ["name", "version", "definitions"] }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "default": "false", "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "publish", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "query", "name": "pack", "required": false } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "string" }, "publish": { "type": "boolean" }, "approvalRequired": { "type": "boolean" }, "definitions": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "approvalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] } }, "required": ["kind", "key", "id", "version", "status", "approvalId"], "additionalProperties": false } }, "lists": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "created": { "type": "boolean" }, "added": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invalid": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["key", "id", "created", "added", "skipped", "invalid"], "additionalProperties": false } } }, "required": [ "name", "version", "publish", "approvalRequired", "definitions", "lists" ], "additionalProperties": false } } } } } } }, "/definitions/packs": { "get": { "summary": "The starter policy packs this deployment ships, to import with ?pack=", "tags": ["definitions"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "counts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": ["id", "name", "version", "description", "counts"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/definitions/usage": { "get": { "summary": "What names each rule, rule set and collection flow", "tags": ["definitions"], "description": "For every definition another one names, the rule sets and workflows whose published or latest version names it (the published version when it does). A workflow uses a rule directly or through a rule set it names. `kind` and `key` narrow the answer; with both, the one item comes back even when nothing names it.", "parameters": [ { "schema": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "query", "name": "key", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "usedBy": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": ["kind", "key", "version", "status"], "additionalProperties": false } } }, "required": ["kind", "key", "usedBy"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/documents": { "post": { "summary": "Register a file and get a presigned PUT to upload it directly to storage", "tags": ["documents"], "description": "Creates a `pending` document and returns the URL and headers the client PUTs the file to, as the request body of exactly `sizeBytes`. Call `finalize` afterwards. Applicants must name their submission and a `file` field of its flow; operators name a subject or a submission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp", "application/pdf"] }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 20971520 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "caseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "fieldKey": { "type": "string" } }, "required": ["fileName", "contentType", "sizeBytes"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "upload": { "type": "object", "properties": { "method": { "type": "string", "enum": ["PUT"] }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["method", "url", "headers", "expiresAt"], "additionalProperties": false } }, "required": ["documentId", "upload"], "additionalProperties": false } } } } } }, "get": { "summary": "Documents of a subject, submission or case, newest first", "tags": ["documents"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "caseId", "required": false }, { "schema": { "type": "string", "enum": ["pending", "uploaded", "scanning", "clean", "infected", "rejected"] }, "in": "query", "name": "status", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "fieldKey": { "type": ["string", "null"] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": ["string", "null"] }, "storageKey": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "uploaded", "scanning", "clean", "infected", "rejected" ] }, "scan": { "anyOf": [ { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "signature": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" } }, "required": ["engine", "scannedAt"], "additionalProperties": false }, { "type": "null" } ] }, "rejectionReason": { "type": ["string", "null"] }, "rejectionCode": { "anyOf": [ { "type": "string", "enum": [ "empty", "too_large", "size_mismatch", "type_mismatch", "unsupported_type", "undecodable_image", "pdf_active_content", "object_missing" ] }, { "type": "null" } ] }, "thumbnailKey": { "type": ["string", "null"] }, "uploadedBy": { "type": "string", "minLength": 1 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "fileName", "contentType", "sizeBytes", "storageKey", "status", "uploadedBy" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/documents/{id}": { "delete": { "summary": "Delete a file of the applicant's own submission while it is in progress", "tags": ["documents"], "description": "Applicants only, with `?submissionId=` naming their submission, which must be `in_progress` (409 otherwise). A document that is `uploaded` or `scanning` answers 409 until the check settles, and an `infected` one stays as the evidence (409). The object and its thumbnail are deleted with the row; audited as `document.deleted`. An answer still naming the file fails the submit check.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } }, "get": { "summary": "A document with its status and scan verdict", "tags": ["documents"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "fieldKey": { "type": ["string", "null"] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": ["string", "null"] }, "storageKey": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["pending", "uploaded", "scanning", "clean", "infected", "rejected"] }, "scan": { "anyOf": [ { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "signature": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" } }, "required": ["engine", "scannedAt"], "additionalProperties": false }, { "type": "null" } ] }, "rejectionReason": { "type": ["string", "null"] }, "rejectionCode": { "anyOf": [ { "type": "string", "enum": [ "empty", "too_large", "size_mismatch", "type_mismatch", "unsupported_type", "undecodable_image", "pdf_active_content", "object_missing" ] }, { "type": "null" } ] }, "thumbnailKey": { "type": ["string", "null"] }, "uploadedBy": { "type": "string", "minLength": 1 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "fileName", "contentType", "sizeBytes", "storageKey", "status", "uploadedBy" ], "additionalProperties": false } } } } } } }, "/documents/{id}/download": { "get": { "summary": "A 60-second presigned download URL for a clean document", "tags": ["documents"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "fileName": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url", "expiresAt", "fileName", "contentType"], "additionalProperties": false } } } } } } }, "/documents/{id}/finalize": { "post": { "summary": "Verify the uploaded object (size, sniffed type, sha256) and queue the scan", "tags": ["documents"], "description": "Idempotent: a document already past `pending` is returned as-is. A file that is empty, over the limit, not the size or type declared, or not an accepted type is deleted and the document marked `rejected`, with `rejectionReason` for people and `rejectionCode` for clients.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "fieldKey": { "type": ["string", "null"] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": ["string", "null"] }, "storageKey": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["pending", "uploaded", "scanning", "clean", "infected", "rejected"] }, "scan": { "anyOf": [ { "type": "object", "properties": { "engine": { "type": "string", "minLength": 1 }, "signature": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" } }, "required": ["engine", "scannedAt"], "additionalProperties": false }, { "type": "null" } ] }, "rejectionReason": { "type": ["string", "null"] }, "rejectionCode": { "anyOf": [ { "type": "string", "enum": [ "empty", "too_large", "size_mismatch", "type_mismatch", "unsupported_type", "undecodable_image", "pdf_active_content", "object_missing" ] }, { "type": "null" } ] }, "thumbnailKey": { "type": ["string", "null"] }, "uploadedBy": { "type": "string", "minLength": 1 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "fileName", "contentType", "sizeBytes", "storageKey", "status", "uploadedBy" ], "additionalProperties": false } } } } } } }, "/documents/{id}/thumbnail": { "get": { "summary": "A 60-second presigned URL to the grayscale thumbnail of a clean document", "tags": ["documents"], "description": "The scan renders a WebP thumbnail, at most 320 by 480 pixels, of every clean image and of the first page of every clean PDF (`thumbnailKey` on the document). 404 when there is none: another type, or a file that did not render. Unlike a download, reading a thumbnail is not audited.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "submissionId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["url", "expiresAt"], "additionalProperties": false } } } } } } }, "/events": { "post": { "summary": "Ingest up to 1 000 events; a repeated idempotencyKey (in the batch or stored) is a duplicate, not an error", "tags": ["events"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "type": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_.-]*$" }, "amount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "occurredAt": {}, "attributes": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255 }, "ip": { "type": "string", "maxLength": 45 }, "deviceId": { "type": "string", "maxLength": 255 }, "cardFingerprint": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "maxLength": 320 } }, "required": ["subjectId", "type", "occurredAt", "idempotencyKey"] } } }, "required": ["events"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duplicates": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["accepted", "duplicates"], "additionalProperties": false } } } } } }, "get": { "summary": "Events newest first, filtered by subject, type and an occurredAt range", "tags": ["events"], "description": "Without `subjects:pii` the `email` column and the personal data in `attributes` are masked; `ip`, `deviceId` and `cardFingerprint` are returned as stored.", "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "type", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "type": { "type": "string", "minLength": 1 }, "amount": { "type": ["number", "null"] }, "currency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "type": "string" }, "ip": { "type": ["string", "null"] }, "deviceId": { "type": ["string", "null"] }, "cardFingerprint": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "subjectId", "type", "occurredAt", "ingestedAt", "attributes", "idempotencyKey" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/health": { "get": { "summary": "Liveness", "tags": ["health"], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"] } }, "required": ["status"], "additionalProperties": false } } } } } } }, "/health/ready": { "get": { "summary": "Readiness (db + temporal)", "tags": ["health"], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "degraded"] }, "checks": { "type": "object", "properties": { "db": { "type": "string", "enum": ["ok", "error"] }, "temporal": { "type": "string", "enum": ["ok", "error"] } }, "required": ["db", "temporal"], "additionalProperties": false } }, "required": ["status", "checks"], "additionalProperties": false } } } } } } }, "/health/summary": { "get": { "summary": "Dependencies, failing apps and given-up webhooks, for the console's health", "tags": ["health"], "description": "`dependencies`: the database, Temporal and object storage (`off` when the deployment has none). `apps` (with `apps:read`): `status` is `off` when the deployment runs no apps (no object storage or no runner), `error` when an app failed a call in the last hour or has an open circuit, `ok` otherwise, with the failing apps and the open circuits. `webhooks` (with `webhooks:read`): deliveries given up on in the last 24 hours and how many endpoints they went to. `state` is `down` when the database is unreachable, `degraded` when anything else is failing, `ok` otherwise. Applicants are refused.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["ok", "degraded", "down"] }, "message": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" }, "dependencies": { "type": "object", "properties": { "db": { "type": "string", "enum": ["ok", "error", "off"] }, "temporal": { "type": "string", "enum": ["ok", "error", "off"] }, "storage": { "type": "string", "enum": ["ok", "error", "off"] } }, "required": ["db", "temporal", "storage"], "additionalProperties": false }, "apps": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "error", "off"] }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "failing": { "type": "array", "items": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "timeouts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p95Ms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "lastInvokedAt": { "type": "string", "format": "date-time" }, "lastErrorAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "appName", "calls", "failures", "timeouts", "p95Ms", "lastInvokedAt", "lastErrorAt" ], "additionalProperties": false } }, "circuits": { "type": "array", "items": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "since": { "type": "string", "format": "date-time" }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["appName", "state", "since", "failures"], "additionalProperties": false } } }, "required": ["status", "windowMinutes", "failing", "circuits"], "additionalProperties": false }, { "type": "null" } ] }, "webhooks": { "anyOf": [ { "type": "object", "properties": { "windowHours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "exhausted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endpoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["windowHours", "exhausted", "endpoints"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["state", "message", "checkedAt", "dependencies", "apps", "webhooks"], "additionalProperties": false } } } } } } }, "/lists": { "get": { "summary": "Every list of the tenant with its live entry count", "tags": ["lists"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "type": "boolean" }, "entryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "name", "kind", "caseInsensitive", "entryCount" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/lists/{key}": { "get": { "summary": "Get a list by key", "tags": ["lists"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "type": "boolean" }, "entryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "name", "kind", "caseInsensitive", "entryCount" ], "additionalProperties": false } } } } } }, "put": { "summary": "Create a list (201) or update its metadata (200)", "tags": ["lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "default": true, "type": "boolean" } }, "required": ["name", "kind"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "type": "boolean" }, "entryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "name", "kind", "caseInsensitive", "entryCount" ], "additionalProperties": false } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["string", "email", "country", "ip_cidr", "number"] }, "caseInsensitive": { "type": "boolean" }, "entryCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "name", "kind", "caseInsensitive", "entryCount" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a list and all its entries (204, empty body)", "tags": ["lists"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/lists/{key}/entries": { "get": { "summary": "Entries newest first, optionally filtered by a substring of the value", "tags": ["lists"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "listId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "value": { "type": "string", "minLength": 1 }, "reason": { "type": ["string", "null"] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "addedBy": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "tenantId", "listId", "value", "addedBy", "createdAt"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Add entries; invalid values are reported by 1-based position, not rejected", "tags": ["lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 512 }, "reason": { "type": "string", "maxLength": 1000 }, "expiresAt": {} }, "required": ["value"] } } }, "required": ["entries"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invalid": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "value": { "type": "string" }, "reason": { "type": "string" } }, "required": ["line", "value", "reason"], "additionalProperties": false } } }, "required": ["added", "skipped", "invalid"], "additionalProperties": false } } } } } }, "delete": { "summary": "Remove entries by id", "tags": ["lists"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } }, "required": ["ids"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["removed"], "additionalProperties": false } } } } } } }, "/lists/{key}/import": { "post": { "summary": "Import entries from CSV (text/csv): one value per line, optional value,reason,expires_at header", "tags": ["lists"], "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invalid": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "value": { "type": "string" }, "reason": { "type": "string" } }, "required": ["line", "value", "reason"], "additionalProperties": false } } }, "required": ["added", "skipped", "invalid"], "additionalProperties": false } } } } } } }, "/me": { "get": { "summary": "The authenticated principal, its tenant and effective permissions", "tags": ["auth"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["human", "machine", "applicant"] }, "subject": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": ["kind", "subject"], "additionalProperties": false }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "orgId": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "subjects:read", "subjects:write", "subjects:pii", "runs:read", "runs:start", "runs:context", "runs:write", "cases:read", "cases:decide", "cases:assign", "cases:claim", "cases:notes", "definitions:read", "definitions:write", "definitions:publish", "definitions:approve", "submissions:read", "submissions:write", "audit:read", "audit:export", "apps:read", "apps:write", "apps:publish", "lists:read", "lists:write", "events:read", "events:write", "backtests:run", "documents:read", "documents:write", "tenants:settings", "ops:read", "webhooks:read", "webhooks:write", "users:manage", "notifications:read" ] } } }, "required": ["principal", "tenantId", "permissions"], "additionalProperties": false } } } } } } }, "/me/preferences": { "get": { "summary": "The caller's console preferences", "tags": ["tenants"], "description": "Time zone, date format, landing page, density and recent searches; unset ones follow the tenant (`console` on `GET /tenants/me`).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "density": { "type": "string", "enum": ["comfortable", "compact"] }, "recentSearches": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": ["recentSearches"], "additionalProperties": false } } } } } }, "put": { "summary": "Replace the caller's console preferences", "tags": ["tenants"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "density": { "type": "string", "enum": ["comfortable", "compact"] }, "recentSearches": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "density": { "type": "string", "enum": ["comfortable", "compact"] }, "recentSearches": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": ["recentSearches"], "additionalProperties": false } } } } } } }, "/notifications": { "get": { "summary": "The caller's notifications, newest first", "tags": ["notifications"], "description": "Notices addressed to the caller, or to a permission the caller holds, and never about what the caller did themselves: `assigned` (a case assigned to you), `sla_breached` (a case you work, or any unassigned one with `cases:assign`, passed its due date), `approval_requested` (`definitions:approve`), `app_degraded` (an app circuit opened; `apps:write`) and `webhook_exhausted` (a delivery was given up; `webhooks:write`). Each has the console path it leads to in `href` and `readAt` once read. `unread=true` lists only the unread; `limit` defaults to 20 (at most 100). `unread` counts the unread ones, up to 1000. They appear a few seconds after the event.", "parameters": [ { "schema": { "type": "string", "enum": ["true", "false"] }, "in": "query", "name": "unread", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": [ "assigned", "sla_breached", "approval_requested", "app_degraded", "webhook_exhausted" ] }, "text": { "type": "string" }, "href": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["id", "kind", "text", "href", "createdAt", "readAt"], "additionalProperties": false } }, "unread": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["items", "unread"], "additionalProperties": false } } } } } } }, "/notifications/read": { "post": { "summary": "Mark notifications read", "tags": ["notifications"], "description": "Marks `ids` (those addressed to the caller; others are ignored), or with `all: true` every unread one, read for the caller only. Answers how many were unread until now.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "all": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "marked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["marked"], "additionalProperties": false } } } } } } }, "/reason-codes": { "get": { "summary": "The tenant's reason-code catalogue, in display order", "tags": ["cases"], "description": "Empty when the tenant keeps none: reviewers then type their own codes. With a catalogue, `POST /cases/:id/decide` accepts only its codes, each for the outcomes it lists (any when empty), and a code with `noteRequired` only with a `note`.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_.-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "outcomes": { "default": [], "type": "array", "items": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "noteRequired": { "default": false, "type": "boolean" } }, "required": ["code", "label", "outcomes", "noteRequired"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "put": { "summary": "Replace the reason-code catalogue", "tags": ["cases"], "description": "The whole catalogue in display order (at most 200, codes unique, lower case letters, digits, `_`, `.` and `-`). An empty list turns the catalogue off. Writes `reason_codes.updated` with the codes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_.-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "outcomes": { "default": [], "type": "array", "items": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "noteRequired": { "default": false, "type": "boolean" } }, "required": ["code", "label"] } } }, "required": ["items"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_.-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "outcomes": { "default": [], "type": "array", "items": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "noteRequired": { "default": false, "type": "boolean" } }, "required": ["code", "label", "outcomes", "noteRequired"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/roles": { "get": { "summary": "The roles and the permissions each grants", "tags": ["tenants"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": ["admin", "analyst", "integration"] }, "permissions": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "permissions"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/rule-definitions": { "get": { "summary": "Latest version of every rule definitions key", "tags": ["rule-definitions"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/rule-definitions/validate": { "post": { "summary": "Validate a draft rule (upsert body) without saving it", "tags": ["rule-definitions"], "description": "Errors: `schema`, `config` (the rule type rejects the config), `unknown_list` (a list lookup names a list that does not exist), `unknown_app` (an app rule names an app the tenant has not installed), `unknown_action` (the installed version has no such action), `async_action` (the action answers through a webhook). Warnings: `unknown_list` (an expression calls `inList` with a list that does not exist), `list_stale` (a list it reads has not changed in over 30 days), `app_disabled`, `rule_disabled`.", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": ["error", "warning"] }, "path": { "type": "string" }, "stepId": { "type": "string" }, "fieldKey": { "type": "string" }, "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": ["severity", "path", "code", "message"], "additionalProperties": false } } }, "required": ["ok", "issues"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}": { "get": { "summary": "Latest version (any status)", "tags": ["rule-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } } } } }, "put": { "summary": "Create a new draft version, with an optional change note", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "default": "block", "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": "number" }, "enabled": { "default": true, "type": "boolean" }, "tags": { "default": [], "type": "array", "items": { "type": "string" } }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "type", "config"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/diff": { "get": { "summary": "Changes between two versions; `to` defaults to the latest, `from` to the published version (else `to - 1`). A workflow diff adds `steps`, the steps one by one", "tags": ["rule-definitions"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "from": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": ["added", "removed", "changed", "moved"] }, "path": { "type": "string" }, "summary": { "type": "string", "minLength": 1 }, "before": {}, "after": {} }, "required": ["op", "path", "summary"], "additionalProperties": false } }, "delta": {}, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": ["added", "removed", "changed", "moved", "unchanged"] }, "from": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "before": { "type": ["string", "null"] }, "after": { "type": ["string", "null"] }, "changes": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "op", "from", "to", "before", "after", "changes"], "additionalProperties": false } } }, "required": ["kind", "key", "from", "to", "changes", "delta"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/dry-run": { "post": { "summary": "Evaluate rule versions against a stored subject or inline data (apps not called), each with an explanation", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "results": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "result": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false }, "explanation": { "type": "string" } }, "required": ["version", "status", "type", "result", "explanation"], "additionalProperties": false } }, "dataPaths": { "type": "array", "items": { "type": "string" } } }, "required": ["key", "results", "dataPaths"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/publish": { "post": { "summary": "Publish the newest draft; archives the previously published version. 409 `approval_required` when the tenant requires approvals", "tags": ["rule-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions": { "get": { "summary": "Every version, newest first, with its latest approval request", "tags": ["rule-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "name": { "type": "string" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "key", "version", "status", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions/{version}": { "patch": { "summary": "Save a draft version in place (the body PUT takes; an absent note keeps the stored one). 409 once it is no longer a draft", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "default": "block", "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": "number" }, "enabled": { "default": true, "type": "boolean" }, "tags": { "default": [], "type": "array", "items": { "type": "string" } }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "type", "config"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } } } } }, "get": { "summary": "One version in full (any status)", "tags": ["rule-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions/{version}/approve": { "post": { "summary": "Approve an open request and publish the version; with four-eyes on, never by its requester", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions/{version}/reject": { "post": { "summary": "Reject an open request; the version goes back to draft", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions/{version}/request-approval": { "post": { "summary": "Ask for a draft version to be approved and published (draft -> pending_approval)", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false } } } } } } }, "/rule-definitions/{key}/versions/{version}/withdraw": { "post": { "summary": "Withdraw an open request; the version goes back to draft. By its requester, or an admin (`tenants:settings`)", "tags": ["rule-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "config": {}, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "enabled": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "type", "config", "severity", "enabled", "tags", "status" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-sets": { "get": { "summary": "Latest version of every rule sets key", "tags": ["rule-sets"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/rule-sets/validate": { "post": { "summary": "Validate a draft rule set (upsert body) without saving it", "tags": ["rule-sets"], "description": "Errors: `schema`, `unknown_rule` (no version of the rule exists). Warnings: `unpublished_rule` (publishing the set needs a published version), `no_live_rules` (every rule is disabled or shadow).", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": ["error", "warning"] }, "path": { "type": "string" }, "stepId": { "type": "string" }, "fieldKey": { "type": "string" }, "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": ["severity", "path", "code", "message"], "additionalProperties": false } } }, "required": ["ok", "issues"], "additionalProperties": false } } } } } } }, "/rule-sets/{key}": { "get": { "summary": "Latest version (any status)", "tags": ["rule-sets"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } } } } }, "put": { "summary": "Create a new draft version, with an optional change note", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "useCase": { "default": "custom", "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey"] } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } } }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"] } } }, "required": ["mode", "bands"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode"] } ] } }, "required": ["rules", "policy"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/diff": { "get": { "summary": "Changes between two versions; `to` defaults to the latest, `from` to the published version (else `to - 1`). A workflow diff adds `steps`, the steps one by one", "tags": ["rule-sets"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "from": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": ["added", "removed", "changed", "moved"] }, "path": { "type": "string" }, "summary": { "type": "string", "minLength": 1 }, "before": {}, "after": {} }, "required": ["op", "path", "summary"], "additionalProperties": false } }, "delta": {}, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": ["added", "removed", "changed", "moved", "unchanged"] }, "from": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "before": { "type": ["string", "null"] }, "after": { "type": ["string", "null"] }, "changes": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "op", "from", "to", "before", "after", "changes"], "additionalProperties": false } } }, "required": ["kind", "key", "from", "to", "changes", "delta"], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/publish": { "post": { "summary": "Publish the newest draft; archives the previously published version. 409 `approval_required` when the tenant requires approvals", "tags": ["rule-sets"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions": { "get": { "summary": "Every version, newest first, with its latest approval request", "tags": ["rule-sets"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "name": { "type": "string" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "key", "version", "status", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions/{version}": { "patch": { "summary": "Save a draft version in place (the body PUT takes; an absent note keeps the stored one). 409 once it is no longer a draft", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "useCase": { "default": "custom", "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey"] } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } } }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"] } } }, "required": ["mode", "bands"] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode"] } ] } }, "required": ["rules", "policy"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } } } } }, "get": { "summary": "One version in full (any status)", "tags": ["rule-sets"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions/{version}/approve": { "post": { "summary": "Approve an open request and publish the version; with four-eyes on, never by its requester", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions/{version}/reject": { "post": { "summary": "Reject an open request; the version goes back to draft", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions/{version}/request-approval": { "post": { "summary": "Ask for a draft version to be approved and published (draft -> pending_approval)", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false } } } } } } }, "/rule-sets/{key}/versions/{version}/withdraw": { "post": { "summary": "Withdraw an open request; the version goes back to draft. By its requester, or an admin (`tenants:settings`)", "tags": ["rule-sets"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "useCase": { "type": "string", "enum": ["onboarding", "underwriting", "monitoring", "custom"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "rules": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "ruleKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "enabled": { "default": true, "type": "boolean" }, "weightOverride": { "type": "number" }, "shadow": { "default": false, "type": "boolean" } }, "required": ["ruleKey", "enabled", "shadow"], "additionalProperties": false } }, "policy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": ["max_severity"] } }, "required": ["mode"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["sum_weights"] }, "clamp": { "default": { "min": 0, "max": 100 }, "type": "object", "properties": { "min": { "default": 0, "type": "number" }, "max": { "default": 100, "type": "number" } }, "required": ["min", "max"], "additionalProperties": false }, "bands": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["min", "max", "outcome"], "additionalProperties": false } } }, "required": ["mode", "clamp", "bands"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["first_match"] }, "default": { "default": "approve", "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["mode", "default"], "additionalProperties": false } ] } }, "required": ["rules", "policy"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "useCase", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/rule-types": { "get": { "summary": "Registered rule types with their config JSON Schemas", "tags": ["rule-definitions"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "comparison", "list_lookup", "score_threshold", "expression", "app", "velocity" ] }, "description": { "type": "string" }, "configSchema": {}, "dataPaths": { "type": "array", "items": { "type": "string" } }, "uiHints": { "type": "object", "properties": { "fieldOrder": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "help": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "listPicker": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "required": ["type", "description", "configSchema", "dataPaths"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/search": { "get": { "summary": "Subjects, cases, runs and definitions matching a name, key or id", "tags": ["search"], "description": "Each `scope` the caller may read is searched at once, `limit` results each: subjects by external id (exact or as a prefix) or name and legal name (as a prefix); cases by the start of their id or by their subject; runs by the start of their id, their correlation id or their subject; definitions (with `definitions:read`) and lists (with `lists:read`) by key or name anywhere, newest version only, exact and leading matches first. A full id, with or without a leading `#`, looks the subject, case or run up directly. A scope the caller may not read is skipped; one that fails or takes over a second comes back empty with `partial: true`. Personal data in subject names is masked as `GET /subjects` masks it.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "q", "required": true }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["subjects", "cases", "runs", "definitions"] } }, "in": "query", "name": "scope", "required": false }, { "schema": { "default": 5, "type": "integer", "exclusiveMinimum": 0, "maximum": 20 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": ["subjects", "cases", "runs", "definitions"] }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subject", "case", "run", "workflow", "rule", "rule_set", "collection_flow", "list" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "href": { "type": "string" } }, "required": ["kind", "id", "title", "subtitle", "href"], "additionalProperties": false } }, "partial": { "type": "boolean" } }, "required": ["scope", "items", "partial"], "additionalProperties": false } }, "tookMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "partial": { "type": "boolean" } }, "required": ["groups", "tookMs", "partial"], "additionalProperties": false } } } } } } }, "/service-users": { "get": { "summary": "The tenant's service users with their keys and last call", "tags": ["service-users"], "description": "The machine users of the tenant's organisation that hold a role on the Aletheia project, by name: `purpose`, `role` (the most privileged held), `enabled`, their personal access tokens (`keys`, with expiry; values are never listed) and `lastCallAt`, the last request the API answered for them (recorded at most once a minute). 503 `service_users_unavailable` without `ZITADEL_MANAGEMENT_PAT`.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["pat"] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["id", "type", "createdAt", "expiresAt"], "additionalProperties": false } }, "lastCallAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "purpose", "role", "enabled", "createdAt", "keys", "lastCallAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } }, "post": { "summary": "Create a service user holding one project role", "tags": ["service-users"], "description": "A machine user named `name` (unique in the identity provider) with `purpose` as its description and `role` (`integration` by default) on the Aletheia project. It has no key yet: issue one with `POST /service-users/:id/keys`. Audited as `service_user.created`. 409 when the name is taken.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9._-]*$" }, "purpose": { "type": "string", "maxLength": 200 }, "role": { "default": "integration", "type": "string", "enum": ["admin", "analyst", "integration"] } }, "required": ["name"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["pat"] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["id", "type", "createdAt", "expiresAt"], "additionalProperties": false } }, "lastCallAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "purpose", "role", "enabled", "createdAt", "keys", "lastCallAt" ], "additionalProperties": false } } } } } } }, "/service-users/{id}": { "patch": { "summary": "Change a service user's purpose, or switch it off and on", "tags": ["service-users"], "description": "`purpose` replaces the description; `enabled: false` deactivates the user, so every key of it is refused, and `true` reactivates it. Audited as `service_user.updated` with what changed. 404 for a user that is not a service user of the tenant. The API checks a key against the identity provider at most once a minute, so a revoked key or a disabled user is refused within a minute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "maxLength": 200 }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": ["pat"] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["id", "type", "createdAt", "expiresAt"], "additionalProperties": false } }, "lastCallAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "purpose", "role", "enabled", "createdAt", "keys", "lastCallAt" ], "additionalProperties": false } } } } } } }, "/service-users/{id}/keys": { "post": { "summary": "Issue a key (personal access token) for a service user, shown once", "tags": ["service-users"], "description": "A personal access token expiring at `expiresAt` (in the future, within 730 days). `token` is in this answer only: store it at once, it cannot be read again. Callers send it as `Authorization: Bearer `. Audited as `service_user.key.created` with the key id and expiry, never the token. 404 for a user that is not a service user of the tenant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": {} }, "required": ["expiresAt"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["id", "token", "expiresAt"], "additionalProperties": false } } } } } } }, "/service-users/{id}/keys/{keyId}": { "delete": { "summary": "Revoke a key of a service user", "tags": ["service-users"], "description": "Deletes the personal access token in the identity provider. Audited as `service_user.key.revoked`. 404 for an unknown key or a user that is not a service user of the tenant. The API checks a key against the identity provider at most once a minute, so a revoked key or a disabled user is refused within a minute.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "keyId", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/setup/checklist": { "get": { "summary": "The tenant's setup steps and which are done", "tags": ["home"], "description": "Computed on each call: `identity` (always done: the tenant has an organization), `team` (someone besides the first admin holds a role, from the reviewer directory), `app` (an app is installed and enabled), `workflow` (a workflow is published), `sla` (a default SLA is set) and `api_key` (an enabled service user holds a key, read from the identity provider). `done` is `null` for a step the API cannot tell: no directory or management credential, or the identity provider failed.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["identity", "team", "app", "workflow", "sla", "api_key"] }, "done": { "type": ["boolean", "null"] }, "detail": { "type": ["string", "null"] }, "href": { "type": ["string", "null"] } }, "required": ["id", "done", "detail", "href"], "additionalProperties": false } }, "done": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "complete": { "type": "boolean" } }, "required": ["items", "done", "total", "complete"], "additionalProperties": false } } } } } } }, "/signup": { "post": { "summary": "Create a workspace: an organisation with an admin, a tenant, and the admin’s temporary password by email", "tags": ["signup"], "description": "Public. Needs a passing Cloudflare Turnstile token (`turnstileToken`) when the deployment checks for bots. One workspace per email (409 `signup_exists`); a deployment caps workspaces per hour (429 `signup_capacity`); 503 `signup_unavailable` when signup is not configured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "company": { "type": "string", "minLength": 2, "maxLength": 80 }, "turnstileToken": { "type": "string", "maxLength": 4096 } }, "required": ["name", "email", "company"] } } } }, "security": [], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "organisation": { "type": "string" }, "orgDomain": { "type": "string" }, "consoleUrl": { "type": "string" } }, "required": ["email", "organisation", "orgDomain", "consoleUrl"], "additionalProperties": false } } } } } } }, "/stats/definitions": { "get": { "summary": "Activity per rule, workflow or collection flow over the last `days` days", "tags": ["stats"], "description": "Over the last `days` days (1 to 90, default 30), per key with any activity: for `rule`, the results recorded by every evaluation (whatever version or set ran it): `evaluated` (passed, failed or errored), `hits` (failed, shadow results included) and `errors`; for `workflow`, the runs started: `runs`, `volumePerDay`, `failed`, `decided` and `autoDecidedPct`; for `collection_flow`, the submissions started: `started`, `submitted`, `completionPct` and `medianDurationMs` from start to submission. Keys without activity are absent. Where each key is used is `GET /definitions/usage`.", "parameters": [ { "schema": { "type": "string", "enum": ["rule", "workflow", "collection_flow"] }, "in": "query", "name": "kind", "required": true }, { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "days", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["rule"] }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["key", "evaluated", "hits", "errors"], "additionalProperties": false } } }, "required": ["kind", "days", "items"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow"] }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "runs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "volumePerDay": { "type": "number", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "decided": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "autoDecidedPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "key", "runs", "volumePerDay", "failed", "decided", "autoDecidedPct" ], "additionalProperties": false } } }, "required": ["kind", "days", "items"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["collection_flow"] }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "started": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "submitted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completionPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "medianDurationMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "key", "started", "submitted", "completionPct", "medianDurationMs" ], "additionalProperties": false } } }, "required": ["kind", "days", "items"], "additionalProperties": false } ] } } } } } } }, "/stats/flows/{key}/funnel": { "get": { "summary": "Where applicants of a flow got to: the steps shown and where the unsent stopped", "tags": ["stats"], "description": "Over the events the collection terminal reported in the last `days` days (1 to 90, default 30), any version of the flow: `opened` counts the submissions shown a step and `submitted` those of them sent. Per step, `reached` counts the submissions shown it and `stoppedHere` those whose last step it was and that are not sent (still in progress, or expired; withdrawn ones are neither). The steps follow the latest version, then the ones only older versions had (`title` null). `uploadFailures` counts the files that did not make it per field and reason, most first. 404 for an unknown flow.", "parameters": [ { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "days", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "days": { "type": "integer", "minimum": 1, "maximum": 90 }, "opened": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "submitted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string" }, "title": { "type": ["string", "null"] }, "reached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "stoppedHere": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["stepId", "title", "reached", "stoppedHere"], "additionalProperties": false } }, "uploadFailures": { "type": "array", "items": { "type": "object", "properties": { "fieldKey": { "type": "string" }, "reason": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["fieldKey", "reason", "count"], "additionalProperties": false } } }, "required": ["key", "days", "opened", "submitted", "steps", "uploadFailures"], "additionalProperties": false } } } } } } }, "/stats/overview": { "get": { "summary": "Home's figures: open cases, the last 24 hours of runs and what needs attention", "tags": ["stats"], "description": "`cases` counts the open and in-review cases: unassigned, breached (past due, or stamped breached), due before `dueBefore` (overdue ones included; default the next midnight in the tenant's `console.timeZone`, else UTC; the console sends the midnight of the zone it shows) and of those the caller's own, plus how long the longest-overdue one is past due. `runs24h` (with `runs:read`) summarises the runs started in the last 24 hours like `GET /workflow-runs/summary`; `autoDecidedPct` is the share of the decided ones decided without a reviewer. `attention` lists, for what the caller may act on: open approval requests with the oldest three (`definitions:approve`), installed apps that are disabled or miss a secret (`apps:write`), apps with failed calls in the last hour or an open circuit (`circuit`; `apps:read`), webhook endpoints with deliveries given up in the last 24 hours (`webhooks:read`) and scheduled audit exports whose run failed in the last 24 hours (`audit:export`). Computed on every request.", "parameters": [ { "schema": {}, "in": "query", "name": "dueBefore", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "object", "properties": { "open": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unassigned": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "breached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dueToday": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dueTodayMine": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "oldestBreachMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "open", "unassigned", "breached", "dueToday", "dueTodayMine", "oldestBreachMs" ], "additionalProperties": false }, "runs24h": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "waiting": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p95Ms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "autoDecidedPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "total", "completed", "waiting", "failed", "p95Ms", "autoDecidedPct" ], "additionalProperties": false }, "attention": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["approvals"] }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "oldest": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "link": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "rule", "rule_set", "collection_flow" ] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["kind", "key", "version"], "additionalProperties": false } }, "required": ["id", "link"], "additionalProperties": false } } }, "required": ["kind", "count", "oldest"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["app_disabled"] }, "app": { "type": "string" } }, "required": ["kind", "app"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["app_unconfigured"] }, "app": { "type": "string" }, "missingSecrets": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": ["kind", "app", "missingSecrets"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["app_failing"] }, "app": { "type": "string" }, "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "timeouts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "circuit": { "type": "string", "enum": ["open", "half_open"] } }, "required": ["kind", "app", "calls", "failures", "timeouts"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["export_failed"] }, "scheduleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "error": { "type": ["string", "null"] } }, "required": ["kind", "scheduleId", "name", "at", "error"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["webhook_exhausted"] }, "endpointId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "event": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["kind", "endpointId", "url", "event", "count"], "additionalProperties": false } ] } } }, "required": ["cases", "attention"], "additionalProperties": false } } } } } } }, "/stats/rules/{key}/hits": { "get": { "summary": "A rule's recorded hits per day, and a backtested version's beside them", "tags": ["stats"], "description": "Days are the tenant's (`console.timeZone`, else UTC; `timeZone` names it). `recorded` has one entry per day of the last `days` days (1 to 90, default 30; today included, oldest first, zero when idle): the rule's results recorded by every evaluation that ran it, `evaluated` (passed, failed or errored) and `hits` (failed). With `compareVersion`, `backtest` is that version's latest completed backtest with its sample per day: how many of the sampled evaluations the recorded result failed (`recordedHits`) against the version (`versionHits`); `null` when it has none. 404 for an unknown rule.", "parameters": [ { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "days", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "compareVersion", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timeZone": { "type": "string" }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["day", "evaluated", "hits"], "additionalProperties": false } }, "backtest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordedHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "versionHits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["day", "evaluated", "recordedHits", "versionHits"], "additionalProperties": false } } }, "required": ["id", "version", "daily"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["key", "days", "timeZone", "recorded", "backtest"], "additionalProperties": false } } } } } } }, "/stats/sla": { "get": { "summary": "SLA attainment, breaches and time to decide over the last `days` days", "tags": ["stats"], "description": "Over the last `days` days (1 to 90, default 30): `decided` cases; `withinPct`, the share of the decided cases with a due date decided by it and never stamped breached; `breached`, the cases stamped breached in the window; `medianDecideMs` from opening to decision; `openPastDue`, the open and in-review cases past due now. `byWorkflow` repeats the window's figures per workflow of the case's run (`workflowKey: null` for cases opened without one), busiest first.", "parameters": [ { "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 }, "in": "query", "name": "days", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "decided": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "withinPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "breached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medianDecideMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "openPastDue": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byWorkflow": { "type": "array", "items": { "type": "object", "properties": { "decided": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "withinPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "breached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medianDecideMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "workflowKey": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, { "type": "null" } ] } }, "required": [ "decided", "withinPct", "breached", "medianDecideMs", "workflowKey" ], "additionalProperties": false } } }, "required": [ "decided", "withinPct", "breached", "medianDecideMs", "days", "openPastDue", "byWorkflow" ], "additionalProperties": false } } } } } } }, "/subjects": { "post": { "summary": "Create a subject", "tags": ["subjects"], "description": "Without `subjects:pii` the personal data in `data` (emails, phone numbers, identity and account numbers, dates of birth, street address lines) is masked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": "string", "minLength": 1 }, "data": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "tags": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": ["kind"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "riskScore": { "type": ["number", "null"] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "kind", "status", "data", "tags" ], "additionalProperties": false } } } } } }, "get": { "summary": "List subjects (newest first), searchable and filterable, with the total", "tags": ["subjects"], "description": "`search` matches `externalId` exactly (case-insensitive) or as a prefix of `externalId`, `data.name` or `data.legalName`. `kind`, `status`, `riskScoreMin` and `riskScoreMax` narrow the list, `country` to the subjects whose country (the first non-blank of `data.country`, `countryCode`, `nationality`, `countryOfResidence` and `address.country`) equals it, case-insensitively, and `lastDecision` to those whose newest decision has that outcome (`none`: no decision; needs `cases:read`). `total` counts the matches, ignoring `limit` and `offset`, and stops at 100,000: `totalIsEstimate` is `true` when it did. `expand=openCases` adds the number of `open` and `in_review` cases of each subject and `expand=lastDecision` its newest decision (`{ outcome, createdAt }`, `null` when there is none), one extra query each; both need `cases:read`. Without `subjects:pii` the personal data in `data` (emails, phone numbers, identity and account numbers, dates of birth, street address lines) is masked.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": ["merchant", "seller", "user"] }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "enum": ["active", "blocked", "closed"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "in": "query", "name": "riskScoreMin", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "in": "query", "name": "riskScoreMax", "required": false }, { "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "in": "query", "name": "country", "required": false }, { "schema": { "type": "string", "enum": ["approve", "reject", "manual_review", "none"] }, "in": "query", "name": "lastDecision", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["openCases", "lastDecision"] } }, "in": "query", "name": "expand", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "riskScore": { "type": ["number", "null"] }, "tags": { "type": "array", "items": { "type": "string" } }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastDecision": { "anyOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["outcome", "createdAt"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "kind", "status", "data", "tags" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/subjects/export": { "get": { "summary": "The filtered subject list as CSV", "tags": ["subjects"], "description": "Every subject matching the `GET /subjects` filters (`limit` and `offset` are ignored; `lastDecision` needs `cases:read`), newest first, at most 10,000: `id, external_id, name, kind, status, country, risk_score, tags, created_at, updated_at` (tags space-separated; a cell starting with `=`, `+`, `-` or `@` is prefixed with `'`). `X-Export-Rows` carries the row count and `X-Export-Truncated: true` says more subjects matched. Personal data is masked without `subjects:pii`. Writes `subject.exported` with the filters and the row count.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": ["merchant", "seller", "user"] }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "enum": ["active", "blocked", "closed"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "in": "query", "name": "riskScoreMin", "required": false }, { "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "in": "query", "name": "riskScoreMax", "required": false }, { "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "in": "query", "name": "country", "required": false }, { "schema": { "type": "string", "enum": ["approve", "reject", "manual_review", "none"] }, "in": "query", "name": "lastDecision", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/subjects/{id}": { "get": { "summary": "Get a subject", "tags": ["subjects"], "description": "`lastSeenAt` is `occurredAt` of the newest event about the subject (`null` without one). Without `subjects:pii` the personal data in `data` (emails, phone numbers, identity and account numbers, dates of birth, street address lines) is masked.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "riskScore": { "type": ["number", "null"] }, "tags": { "type": "array", "items": { "type": "string" } }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "kind", "status", "data", "tags", "lastSeenAt" ], "additionalProperties": false } } } } } }, "patch": { "summary": "Change a subject's data, tags or status", "tags": ["subjects"], "description": "`data` is a JSON merge patch (RFC 7396): objects merge key by key, `null` removes a key, any other value replaces it, so send only what changes; values you read masked stay as stored unless you send new ones. `tags` replaces the list and `status` sets the status (`active`, `blocked`, `closed`). Writes `subject.updated` with the paths that changed (`data.address.city`, `tags`, `status`), never their values; a request that changes nothing writes no event. Without `subjects:pii` the personal data in `data` (emails, phone numbers, identity and account numbers, dates of birth, street address lines) is masked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "tags": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "externalId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "blocked", "closed"] }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "riskScore": { "type": ["number", "null"] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "kind", "status", "data", "tags" ], "additionalProperties": false } } } } } } }, "/subjects/{id}/flags": { "get": { "summary": "Signals derived from what the platform holds about a subject", "tags": ["subjects"], "description": "`high_risk` (a score of 90 or more), `rule_hit` (each rule that failed on the newest decision, not counting shadow rules; severity from the rule), `new_device` (the newest event came from a device none of the earlier events used, when there were earlier devices), `shared_device` and `shared_card` (`detail`: how many subjects share one) and `info_requested` (`detail`: the case waiting for the applicant). `rule_hit` and `info_requested` need `cases:read` and are left out without it. Computed on each request.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rule_hit", "high_risk", "new_device", "shared_device", "shared_card", "info_requested" ] }, "severity": { "type": "string", "enum": ["info", "warn", "high"] }, "label": { "type": "string" }, "detail": { "type": ["string", "null"] } }, "required": ["code", "severity", "label", "detail"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/subjects/{id}/links": { "get": { "summary": "Subjects that share a device, card, IP address, email, address or referral", "tags": ["subjects"], "description": "`via` says what is shared: `device`, `card`, `ip` and `email` from the events (the keys of the subject's newest 200 events), `address` for the same `data.address` object and `referral` when one's `data.referredBy` is the other's external id. `lastSharedAt` is the newest event of the other subject carrying a shared key (`null` for data links). Most recent first, at most 50. The summaries carry names as on `expand=subject`; the shared values are not returned.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "externalId": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "country": { "type": "string" }, "displayName": { "type": "string" } }, "required": ["id", "kind", "displayName"], "additionalProperties": false }, "via": { "type": "array", "items": { "type": "string", "enum": ["device", "card", "ip", "email", "address", "referral"] } }, "lastSharedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": ["subject", "via", "lastSharedAt"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/subjects/{id}/timeline": { "get": { "summary": "The subject history: decisions, cases, runs, submissions, documents, events, notes and audit, newest first", "tags": ["subjects"], "description": "One stream merged from the entity tables and the audit log. Each kind needs its own read permission (`cases:read` for decision/case/note, `runs:read`, `submissions:read`, `documents:read`, `events:read`, `audit:read`); kinds the caller may not read are left out silently. `kinds` is a repeated param; `from`/`to` bound the entry time. A page holds up to `limit` entries (default 50, max 500); pass its `nextCursor` as `cursor` for the entries after it, until `nextCursor` is `null`. Entry `data` follows the same masking and redaction as the entity routes and, for audit entries, `GET /audit-events` (`subjects:pii`, `runs:context`).", "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "decision", "case", "run", "submission", "document", "event", "note", "audit" ] } }, "in": "query", "name": "kinds", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "decision", "case", "run", "submission", "document", "event", "note", "audit" ] }, "at": { "type": "string", "format": "date-time" }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string" }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "service", "applicant", "system", "app", "workflow" ] }, "id": { "type": "string", "minLength": 1 } }, "required": ["type", "id"], "additionalProperties": false }, "data": {} }, "required": ["id", "kind", "at", "title", "resourceType", "resourceId"], "additionalProperties": false } }, "nextCursor": { "type": ["string", "null"] } }, "required": ["items", "nextCursor"], "additionalProperties": false } } } } } } }, "/team/invitations": { "post": { "summary": "Invite someone with a role", "tags": ["team"], "description": "Creates the person in the organization with the role and has the identity provider mail them an invitation; they show as `invited` until they accept. Audited as `team.user.invited`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "enum": ["admin", "analyst"] } }, "required": ["email", "name", "role"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "invited", "deactivated"] }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "status", "lastActiveAt", "openCases", "invitedAt" ], "additionalProperties": false } } } } } } }, "/team/users": { "get": { "summary": "The organization's people holding a role", "tags": ["team"], "description": "Each with the most privileged role they hold, `status` (`active`, `invited` until they accept, `deactivated`), when the API last answered them and their open and in-review cases. 503 `team_unavailable` without `ZITADEL_MANAGEMENT_PAT`.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "invited", "deactivated"] }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "status", "lastActiveAt", "openCases", "invitedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/team/users/{id}/deactivate": { "post": { "summary": "Deactivate someone", "tags": ["team"], "description": "They can no longer sign in; their cases stay assigned until someone reassigns them. Not your own (409). Audited as `team.user.deactivated`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "invited", "deactivated"] }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "status", "lastActiveAt", "openCases", "invitedAt" ], "additionalProperties": false } } } } } } }, "/team/users/{id}/invitation": { "delete": { "summary": "Cancel an invitation", "tags": ["team"], "description": "Deletes the person, who never signed in; 409 once they accepted (deactivate them instead). Audited as `team.invitation.cancelled`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/team/users/{id}/reactivate": { "post": { "summary": "Reactivate someone", "tags": ["team"], "description": "They can sign in again. Not your own (409). Audited as `team.user.reactivated`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "invited", "deactivated"] }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "status", "lastActiveAt", "openCases", "invitedAt" ], "additionalProperties": false } } } } } } }, "/team/users/{id}/resend-invitation": { "post": { "summary": "Mail an invitation again", "tags": ["team"], "description": "409 once they accepted. Audited as `team.invitation.resent`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/team/users/{id}/role": { "put": { "summary": "Change someone's role", "tags": ["team"], "description": "Takes effect when their access token is next refreshed, within minutes. Not your own (409). Audited as `team.user.role_changed` with the old and new role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "analyst"] } }, "required": ["role"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": ["string", "null"] }, "role": { "anyOf": [ { "type": "string", "enum": ["admin", "analyst", "integration"] }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "invited", "deactivated"] }, "lastActiveAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "openCases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "invitedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "role", "status", "lastActiveAt", "openCases", "invitedAt" ], "additionalProperties": false } } } } } } }, "/tenants/me": { "get": { "summary": "The caller's tenant: its state, the console's defaults and how much it holds", "tags": ["tenants"], "description": "Answers while the tenant is suspended too. `counts.auditEvents` stops at 100,000 (`auditEventsIsEstimate`).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "idpOrgId": { "type": ["string", "null"] }, "provisionedAt": { "type": "string", "format": "date-time" }, "region": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "suspended"] }, "suspendedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "suspendedReason": { "type": ["string", "null"] }, "linksValidAfter": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "console": { "type": "object", "properties": { "workspaceName": { "type": "string" }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false }, "counts": { "type": "object", "properties": { "subjects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEvents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEventsIsEstimate": { "type": "boolean" } }, "required": [ "subjects", "cases", "documents", "documentBytes", "auditEvents", "auditEventsIsEstimate" ], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "console", "counts" ], "additionalProperties": false } } } } } } }, "/tenants/me/resume": { "post": { "summary": "Resume a suspended tenant", "tags": ["tenants"], "description": "Audited as `tenant.resumed`. Needs `tenants:settings` and a sign-in under five minutes old: the ID token of it in `X-Aletheia-Reauth` (401 `reauth_required` otherwise).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "idpOrgId": { "type": ["string", "null"] }, "provisionedAt": { "type": "string", "format": "date-time" }, "region": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "suspended"] }, "suspendedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "suspendedReason": { "type": ["string", "null"] }, "linksValidAfter": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "console": { "type": "object", "properties": { "workspaceName": { "type": "string" }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false }, "counts": { "type": "object", "properties": { "subjects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEvents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEventsIsEstimate": { "type": "boolean" } }, "required": [ "subjects", "cases", "documents", "documentBytes", "auditEvents", "auditEventsIsEstimate" ], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "console", "counts" ], "additionalProperties": false } } } } } } }, "/tenants/me/revoke-links": { "post": { "summary": "Stop every collection link issued until now from opening", "tags": ["tenants"], "description": "For a leaked link or a compromised channel: links issued before now answer 401; the forms stay in progress, and `POST /collection-submissions/{id}/link` issues new links. `revokedLinks` counts the forms in progress. Other API instances follow within five minutes. Audited as `tenant.links.revoked`. Needs `tenants:settings` and a sign-in under five minutes old: the ID token of it in `X-Aletheia-Reauth` (401 `reauth_required` otherwise).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "revokedLinks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "validAfter": { "type": "string", "format": "date-time" } }, "required": ["revokedLinks", "validAfter"], "additionalProperties": false } } } } } } }, "/tenants/me/settings": { "get": { "summary": "The caller's tenant settings", "tags": ["tenants"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "embedOrigins": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^https?:\\/\\/[a-z0-9.-]+(:\\d{1,5})?$" } }, "cases": { "default": {}, "type": "object", "properties": { "defaultSlaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "businessHours": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "timeZone": { "default": "UTC", "type": "string" }, "days": { "default": [1, 2, 3, 4, 5], "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "start": { "default": "09:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "default": "18:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": ["enabled", "timeZone", "days", "start", "end"], "additionalProperties": false }, "warnAtPct": { "type": "integer", "minimum": 1, "maximum": 99 }, "onBreach": { "type": "object", "properties": { "escalatePriority": { "default": true, "type": "boolean" }, "notifyAssignee": { "default": true, "type": "boolean" }, "notifyAssigners": { "default": true, "type": "boolean" } }, "required": ["escalatePriority", "notifyAssignee", "notifyAssigners"], "additionalProperties": false } }, "additionalProperties": false }, "approvals": { "default": { "required": false, "fourEyes": true }, "type": "object", "properties": { "required": { "default": false, "type": "boolean" }, "fourEyes": { "default": true, "type": "boolean" }, "requiredFor": { "type": "array", "items": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow", "app"] } } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "collection": { "default": {}, "type": "object", "properties": { "flowUrl": { "type": "string", "format": "uri" }, "defaultLinkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "abandonAfterDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "locales": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" } } }, "additionalProperties": false }, "console": { "default": {}, "type": "object", "properties": { "workspaceName": { "type": "string", "minLength": 1, "maxLength": 80 }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "showRunContextTo": { "type": "string", "enum": ["admins", "all"] }, "maskForAnalysts": { "type": "array", "items": { "type": "string", "enum": ["email", "phone", "document", "dateOfBirth", "address"] } } }, "additionalProperties": false }, "branding": { "default": {}, "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": "string", "format": "uri" }, "logoDarkUrl": { "type": "string", "format": "uri" }, "logoAlt": { "type": "string", "minLength": 1, "maxLength": 120 }, "primary": { "type": "string", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$" }, "radius": { "type": "number", "minimum": 0, "maximum": 24 }, "controlRadius": { "type": "number", "minimum": 0, "maximum": 24 }, "borderWidth": { "type": "number", "minimum": 1, "maximum": 2 }, "headingWeight": { "type": "integer", "minimum": 500, "maximum": 900 }, "font": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w\\s,'\"-]+$" }, "colorScheme": { "type": "string", "enum": ["light", "dark", "system"] }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "supportUrl": { "type": "string", "format": "uri" }, "privacyUrl": { "type": "string", "format": "uri" }, "termsUrl": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "embedOrigins", "cases", "approvals", "collection", "console", "branding" ], "additionalProperties": false } } } } } }, "put": { "summary": "Replace the caller's tenant settings", "tags": ["tenants"], "description": "`embedOrigins`: origins that may embed the collection flow. `cases`: `defaultSlaHours`, `businessHours` (the hours SLA clocks run in: `enabled`, `timeZone`, ISO `days`, `start`, `end`), `warnAtPct` (the share of the SLA left when a new case turns `due_soon`) and `onBreach` (`escalatePriority`, `notifyAssignee`, `notifyAssigners`). `approvals`: `required`, `fourEyes` and `requiredFor`, the definition kinds approvals apply to (unset: all). `collection`: `flowUrl`, the tenant's own address of the collection terminal, which its links point at, `defaultLinkTtlSeconds`, the lifetime of links for flows that set none, `abandonAfterDays`, after which forms nobody saved expire (the worker looks hourly; a run waiting for one is cancelled; a request for information keeps its own expiry), and `locales`, the languages applicants may read the tenant's forms in as canonical language tags (`fr`, `pt-BR`; unset, English), the first being the one flows are written in and the others coming from each flow's `translations`. `console`: the defaults everyone's console starts from (`workspaceName`, `timeZone`, `dateFormat`, `landing`, `checklist`, `idleLockMinutes`), which a person's preferences override, and what people see: `showRunContextTo` (`admins`, the holders of `runs:context`, or `all`) and `maskForAnalysts`, the kinds of personal data masked for people without `subjects:pii` (`email`, `phone`, `document`, `dateOfBirth`, `address`; unset, all). Machine callers keep the permission rules. Other API instances apply those two within 30 seconds. `branding`: how the collection terminal looks for the tenant's applicants and whom they contact (`name`, `logoUrl`, `logoDarkUrl`, `logoAlt`, `primary`, `radius`, `controlRadius`, `borderWidth`, `headingWeight`, `font`, `colorScheme`, `supportEmail`, `supportUrl`, `privacyUrl`, `termsUrl`, `returnUrl`), over the deployment's defaults; addresses are https. Audited as `tenant.settings.updated` with the dotted paths that changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "embedOrigins": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^https?:\\/\\/[a-z0-9.-]+(:\\d{1,5})?$" } }, "cases": { "default": {}, "type": "object", "properties": { "defaultSlaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "businessHours": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "timeZone": { "default": "UTC", "type": "string" }, "days": { "default": [1, 2, 3, 4, 5], "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "start": { "default": "09:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "default": "18:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "warnAtPct": { "type": "integer", "minimum": 1, "maximum": 99 }, "onBreach": { "type": "object", "properties": { "escalatePriority": { "default": true, "type": "boolean" }, "notifyAssignee": { "default": true, "type": "boolean" }, "notifyAssigners": { "default": true, "type": "boolean" } } } } }, "approvals": { "default": { "required": false, "fourEyes": true }, "type": "object", "properties": { "required": { "default": false, "type": "boolean" }, "fourEyes": { "default": true, "type": "boolean" }, "requiredFor": { "type": "array", "items": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow", "app"] } } } }, "collection": { "default": {}, "type": "object", "properties": { "flowUrl": { "type": "string", "format": "uri" }, "defaultLinkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "abandonAfterDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "locales": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" } } } }, "console": { "default": {}, "type": "object", "properties": { "workspaceName": { "type": "string", "minLength": 1, "maxLength": 80 }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "showRunContextTo": { "type": "string", "enum": ["admins", "all"] }, "maskForAnalysts": { "type": "array", "items": { "type": "string", "enum": ["email", "phone", "document", "dateOfBirth", "address"] } } } }, "branding": { "default": {}, "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": "string", "format": "uri" }, "logoDarkUrl": { "type": "string", "format": "uri" }, "logoAlt": { "type": "string", "minLength": 1, "maxLength": 120 }, "primary": { "type": "string", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$" }, "radius": { "type": "number", "minimum": 0, "maximum": 24 }, "controlRadius": { "type": "number", "minimum": 0, "maximum": 24 }, "borderWidth": { "type": "number", "minimum": 1, "maximum": 2 }, "headingWeight": { "type": "integer", "minimum": 500, "maximum": 900 }, "font": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w\\s,'\"-]+$" }, "colorScheme": { "type": "string", "enum": ["light", "dark", "system"] }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "supportUrl": { "type": "string", "format": "uri" }, "privacyUrl": { "type": "string", "format": "uri" }, "termsUrl": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" } } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "embedOrigins": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^https?:\\/\\/[a-z0-9.-]+(:\\d{1,5})?$" } }, "cases": { "default": {}, "type": "object", "properties": { "defaultSlaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "businessHours": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "timeZone": { "default": "UTC", "type": "string" }, "days": { "default": [1, 2, 3, 4, 5], "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "start": { "default": "09:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "default": "18:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": ["enabled", "timeZone", "days", "start", "end"], "additionalProperties": false }, "warnAtPct": { "type": "integer", "minimum": 1, "maximum": 99 }, "onBreach": { "type": "object", "properties": { "escalatePriority": { "default": true, "type": "boolean" }, "notifyAssignee": { "default": true, "type": "boolean" }, "notifyAssigners": { "default": true, "type": "boolean" } }, "required": ["escalatePriority", "notifyAssignee", "notifyAssigners"], "additionalProperties": false } }, "additionalProperties": false }, "approvals": { "default": { "required": false, "fourEyes": true }, "type": "object", "properties": { "required": { "default": false, "type": "boolean" }, "fourEyes": { "default": true, "type": "boolean" }, "requiredFor": { "type": "array", "items": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow", "app"] } } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "collection": { "default": {}, "type": "object", "properties": { "flowUrl": { "type": "string", "format": "uri" }, "defaultLinkTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "abandonAfterDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "locales": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?(?:-(?:[a-z0-9]{5,8}|[0-9][a-z0-9]{3}))*$" } } }, "additionalProperties": false }, "console": { "default": {}, "type": "object", "properties": { "workspaceName": { "type": "string", "minLength": 1, "maxLength": 80 }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "showRunContextTo": { "type": "string", "enum": ["admins", "all"] }, "maskForAnalysts": { "type": "array", "items": { "type": "string", "enum": ["email", "phone", "document", "dateOfBirth", "address"] } } }, "additionalProperties": false }, "branding": { "default": {}, "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "logoUrl": { "type": "string", "format": "uri" }, "logoDarkUrl": { "type": "string", "format": "uri" }, "logoAlt": { "type": "string", "minLength": 1, "maxLength": 120 }, "primary": { "type": "string", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$" }, "radius": { "type": "number", "minimum": 0, "maximum": 24 }, "controlRadius": { "type": "number", "minimum": 0, "maximum": 24 }, "borderWidth": { "type": "number", "minimum": 1, "maximum": 2 }, "headingWeight": { "type": "integer", "minimum": 500, "maximum": 900 }, "font": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w\\s,'\"-]+$" }, "colorScheme": { "type": "string", "enum": ["light", "dark", "system"] }, "supportEmail": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "supportUrl": { "type": "string", "format": "uri" }, "privacyUrl": { "type": "string", "format": "uri" }, "termsUrl": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "required": [ "embedOrigins", "cases", "approvals", "collection", "console", "branding" ], "additionalProperties": false } } } } } } }, "/tenants/me/suspend": { "post": { "summary": "Suspend the tenant", "tags": ["tenants"], "description": "Every route but the tenant's profile, the roles, preferences, the health summary and resuming then answers 403 `tenant_suspended` with the reason, and collection links stop opening; other API instances follow within five minutes. Runs already under way keep running. Audited as `tenant.suspended`. Needs `tenants:settings` and a sign-in under five minutes old: the ID token of it in `X-Aletheia-Reauth` (401 `reauth_required` otherwise).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": ["reason"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "name": { "type": "string" }, "idpOrgId": { "type": ["string", "null"] }, "provisionedAt": { "type": "string", "format": "date-time" }, "region": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "suspended"] }, "suspendedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "suspendedReason": { "type": ["string", "null"] }, "linksValidAfter": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "console": { "type": "object", "properties": { "workspaceName": { "type": "string" }, "timeZone": { "type": "string" }, "dateFormat": { "type": "string", "enum": ["24h", "12h"] }, "landing": { "type": "string", "enum": ["home", "cases", "runs"] }, "checklist": { "type": "string", "enum": ["until_done", "hidden"] }, "idleLockMinutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false }, "counts": { "type": "object", "properties": { "subjects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cases": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "documentBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEvents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "auditEventsIsEstimate": { "type": "boolean" } }, "required": [ "subjects", "cases", "documents", "documentBytes", "auditEvents", "auditEventsIsEstimate" ], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "console", "counts" ], "additionalProperties": false } } } } } } }, "/users": { "get": { "summary": "The tenant's reviewers, optionally those holding one role", "tags": ["users"], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "role", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "name", "roles"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/webhook-deliveries": { "get": { "summary": "Deliveries of events to the endpoints, newest first", "tags": ["webhooks"], "description": "Filtered by endpoint, `status` (repeatable: `pending`, `delivered`, `failed` with another attempt to come, `exhausted` once given up), event, run and creation time (`from`/`to`, inclusive). Each carries the body it sends (`payload`), its attempts, the last response code or error and when the next attempt goes out.", "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "endpointId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["pending", "delivered", "failed", "exhausted"] } }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, "in": "query", "name": "event", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "workflowRunId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "endpointId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "eventId": { "type": "string" }, "event": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["pending", "delivered", "failed", "exhausted"] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastResponseCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastError": { "type": ["string", "null"] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, { "type": "string", "enum": ["ping"] } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "occurredAt", "tenantId", "resource", "data" ], "additionalProperties": false } }, "required": [ "id", "endpointId", "eventId", "event", "resource", "workflowRunId", "status", "attempts", "lastResponseCode", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "payload" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/webhook-deliveries/{id}/retry": { "post": { "summary": "Send a failed or given-up delivery again", "tags": ["webhooks"], "description": "Makes the delivery due now: the worker attempts it within seconds, and a failure that leaves attempts goes back on the retry schedule (a given-up delivery gets one more attempt). A pending delivery is returned as it is. Audited as `webhook_delivery.retried`. 409 for a delivered one.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "endpointId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "eventId": { "type": "string" }, "event": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["pending", "delivered", "failed", "exhausted"] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastResponseCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastError": { "type": ["string", "null"] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, { "type": "string", "enum": ["ping"] } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["id", "type", "occurredAt", "tenantId", "resource", "data"], "additionalProperties": false } }, "required": [ "id", "endpointId", "eventId", "event", "resource", "workflowRunId", "status", "attempts", "lastResponseCode", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "payload" ], "additionalProperties": false } } } } } } }, "/webhook-endpoints": { "get": { "summary": "The tenant's webhook endpoints", "tags": ["webhooks"], "description": "Oldest first, with `lastDeliveryAt` (the newest attempt) and `failing` (that attempt failed or was the last). Secrets are never returned here.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failing": { "type": "boolean" } }, "required": [ "id", "url", "description", "events", "enabled", "createdAt", "updatedAt", "previousSecretExpiresAt", "lastDeliveryAt", "failing" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } }, "post": { "summary": "Add a webhook endpoint", "tags": ["webhooks"], "description": "Creates the endpoint and its signing secret (`whsec_…`), returned in `secret` this once and sealed with `SECRET_STORE_KEY`. Deliveries are POSTed as JSON with `X-Aletheia-Event`, `X-Aletheia-Delivery` and `X-Aletheia-Signature: t=,v1=.\">`; a 2xx answer within 10 s counts as delivered, anything else is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then given up. The URL must be https and must not name localhost or a private address (names resolving to one are refused when sending) unless the deployment sets `WEBHOOK_ALLOW_PRIVATE_NETWORKS`. Events that happen from now on are delivered. Audited as `webhook_endpoint.created`. At most 20 endpoints per tenant. 503 `secret_store_unavailable` without a key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "maxLength": 200 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "default": true, "type": "boolean" } }, "required": ["url", "events"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failing": { "type": "boolean" }, "secret": { "type": "string" } }, "required": [ "id", "url", "description", "events", "enabled", "createdAt", "updatedAt", "previousSecretExpiresAt", "lastDeliveryAt", "failing", "secret" ], "additionalProperties": false } } } } } } }, "/webhook-endpoints/{id}": { "get": { "summary": "One webhook endpoint", "tags": ["webhooks"], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failing": { "type": "boolean" } }, "required": [ "id", "url", "description", "events", "enabled", "createdAt", "updatedAt", "previousSecretExpiresAt", "lastDeliveryAt", "failing" ], "additionalProperties": false } } } } } }, "put": { "summary": "Change a webhook endpoint", "tags": ["webhooks"], "description": "Replaces the URL, description, events and `enabled`; the secret is kept. A disabled endpoint receives nothing: its queued deliveries wait until it is enabled again. Audited as `webhook_endpoint.updated` with the fields that changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "maxLength": 200 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "default": true, "type": "boolean" } }, "required": ["url", "events"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failing": { "type": "boolean" } }, "required": [ "id", "url", "description", "events", "enabled", "createdAt", "updatedAt", "previousSecretExpiresAt", "lastDeliveryAt", "failing" ], "additionalProperties": false } } } } } }, "delete": { "summary": "Delete a webhook endpoint and its deliveries", "tags": ["webhooks"], "description": "Audited as `webhook_endpoint.deleted` with its URL.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/webhook-endpoints/{id}/rotate-secret": { "post": { "summary": "Replace a webhook endpoint's signing secret", "tags": ["webhooks"], "description": "Returns the new secret this once. For the next 24 hours deliveries carry two `v1` signatures, one per secret, so the receiver can switch over; after that only the new one. Rotating again within the 24 hours drops the oldest secret at once. Audited as `webhook_endpoint.secret.rotated`. 503 `secret_store_unavailable` without a key.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "previousSecretExpiresAt": { "type": "string", "format": "date-time" } }, "required": ["secret", "previousSecretExpiresAt"], "additionalProperties": false } } } } } } }, "/webhook-endpoints/{id}/test": { "post": { "summary": "Send a ping to a webhook endpoint now", "tags": ["webhooks"], "description": "POSTs a signed `ping` (`type: \"ping\"`, the endpoint as `resource`, empty `data`) once, enabled or not, and answers what came back: `delivered` for a 2xx, the response code and the time taken, or the error. Nothing is stored besides the `webhook_endpoint.tested` audit event. 503 `secret_store_unavailable` without a key.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "responseCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "latencyMs": { "type": "number", "minimum": 0 }, "error": { "type": "string" } }, "required": ["delivered", "responseCode", "latencyMs"], "additionalProperties": false } } } } } } }, "/webhook-events": { "get": { "summary": "The events an endpoint can subscribe to", "tags": ["webhooks"], "description": "Every event with what raises it, the type of resource it is about and a sample of the body a delivery carries: `{ id, type, occurredAt, tenantId, resource: { type, id }, data }`, where `id` is the event id (the same on every attempt) and `data` the audit payload of the change.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, "description": { "type": "string" }, "resourceType": { "type": "string" }, "samplePayload": {} }, "required": ["name", "description", "resourceType", "samplePayload"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/webhooks/apps/{app}": { "post": { "summary": "Vendor webhook for an asynchronous call of a platform app (checked by the app)", "tags": ["webhooks"], "description": "The external id is `?externalId=` when present, else read where the newest published platform version of the app declares it (`handles.webhookExternalId`: a JSON Pointer into a JSON body, a header or a query parameter); 400 `missing_external_id` without one. 404 when no session waits on the id; 409 `app_not_installed` when the tenant removed the app; 401 `webhook_rejected` when the app refuses the signature or payload; 502 `app_webhook_failed` when the app or the runner fails. 202 `{ ignored: true }` for a request the app drops, 200 `{ duplicate: true }` for a replayed event, 200 `{ stale: true }` for a session already settled, 202 `{ accepted: true }` for an event that keeps the session pending; otherwise the session completes and the answer names it with its `status`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "externalId", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "app", "required": true } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "callbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "accepted": { "type": "boolean" }, "ignored": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": ["received"], "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "callbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "accepted": { "type": "boolean" }, "ignored": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": ["received"], "additionalProperties": false } } } } } } }, "/webhooks/apps/{app}/tenants/{tenantId}": { "post": { "summary": "Vendor webhook for an asynchronous call of a tenant's own app (checked by the app)", "tags": ["webhooks"], "description": "The same as `POST /webhooks/apps/:app`, for the apps a tenant uploaded: the sessions are only that tenant's own app's, and the external id, when not in `?externalId=`, is read where the tenant's newest published version of the app declares it. A webhook to the platform route never reaches a tenant's app of the same name, nor this route another tenant's.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "externalId", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "app", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "tenantId", "required": true } ], "security": [], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "callbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "accepted": { "type": "boolean" }, "ignored": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": ["received"], "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" }, "callbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": ["pending", "completed", "failed", "timed_out"] }, "accepted": { "type": "boolean" }, "ignored": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": ["received"], "additionalProperties": false } } } } } } }, "/workflow-definitions": { "get": { "summary": "Latest version of every workflow definitions key", "tags": ["workflow-definitions"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": [ "id", "type", "caseType", "priority", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": [ "id", "type", "mode", "rulesKey", "manualDecisionKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/workflow-definitions/context-paths": { "post": { "summary": "The run-context paths a step can read, with their type and the step that writes them", "tags": ["workflow-definitions"], "description": "Takes a workflow `definition`, saved or not, and the reading `stepId`. Lists what every run starts with (`subjectId`, `subject`), then the paths the steps that can run before it write: each output key and, where known, its fields (a rule aggregate, a manual decision, the latest version of a flow's fields, the output of an action of the app version the tenant installed). `always` is true when every path to the step runs the writer. Without `stepId`, every step's writes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": {}, "stepId": { "type": "string" } }, "required": ["definition"] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type": { "type": "string", "enum": ["string", "number", "boolean", "object", "array", "unknown"] }, "writtenBy": { "type": ["string", "null"] }, "always": { "type": "boolean" } }, "required": ["path", "type", "writtenBy", "always"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/workflow-definitions/validate": { "post": { "summary": "Validate a draft workflow definition (upsert body) without saving it", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": ["error", "warning"] }, "path": { "type": "string" }, "stepId": { "type": "string" }, "fieldKey": { "type": "string" }, "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": ["severity", "path", "code", "message"], "additionalProperties": false } } }, "required": ["ok", "issues"], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}": { "get": { "summary": "Latest version (any status)", "tags": ["workflow-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type", "mode", "rulesKey", "manualDecisionKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } } } } }, "put": { "summary": "Create a new draft version, with an optional change note", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trigger": { "default": "manual", "type": "string", "enum": ["manual", "subject.created", "event"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } } } }, "required": ["id", "type", "app", "action", "outputKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"] } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"] } } } } }, "required": ["entryStepId", "steps"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type", "mode", "rulesKey", "manualDecisionKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/diff": { "get": { "summary": "Changes between two versions; `to` defaults to the latest, `from` to the published version (else `to - 1`). A workflow diff adds `steps`, the steps one by one", "tags": ["workflow-definitions"], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "from": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": ["added", "removed", "changed", "moved"] }, "path": { "type": "string" }, "summary": { "type": "string", "minLength": 1 }, "before": {}, "after": {} }, "required": ["op", "path", "summary"], "additionalProperties": false } }, "delta": {}, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": ["added", "removed", "changed", "moved", "unchanged"] }, "from": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "before": { "type": ["string", "null"] }, "after": { "type": ["string", "null"] }, "changes": { "type": "array", "items": { "type": "string" } } }, "required": ["id", "op", "from", "to", "before", "after", "changes"], "additionalProperties": false } } }, "required": ["kind", "key", "from", "to", "changes", "delta"], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/publish": { "post": { "summary": "Publish the newest draft; archives the previously published version. 409 `approval_required` when the tenant requires approvals", "tags": ["workflow-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type", "mode", "rulesKey", "manualDecisionKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions": { "get": { "summary": "Every version, newest first, with its latest approval request", "tags": ["workflow-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "name": { "type": "string" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "key", "version", "status", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions/{version}": { "patch": { "summary": "Save a draft version in place (the body PUT takes; an absent note keeps the stored one). 409 once it is no longer a draft", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "trigger": { "default": "manual", "type": "string", "enum": ["manual", "subject.created", "event"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } } } }, "required": ["id", "type", "app", "action", "outputKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type"] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"] }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"] } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"] } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"] } } } } }, "required": ["entryStepId", "steps"] }, "note": { "type": "string", "maxLength": 200 } }, "required": ["name", "definition"] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type", "mode", "rulesKey", "manualDecisionKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } } } } }, "get": { "summary": "One version in full (any status)", "tags": ["workflow-definitions"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": ["id", "type", "mode", "rulesKey", "manualDecisionKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions/{version}/approve": { "post": { "summary": "Approve an open request and publish the version; with four-eyes on, never by its requester", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": [ "id", "type", "mode", "rulesKey", "manualDecisionKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions/{version}/reject": { "post": { "summary": "Reject an open request; the version goes back to draft", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": [ "id", "type", "mode", "rulesKey", "manualDecisionKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions/{version}/request-approval": { "post": { "summary": "Ask for a draft version to be approved and published (draft -> pending_approval)", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false } } } } } } }, "/workflow-definitions/{key}/versions/{version}/withdraw": { "post": { "summary": "Withdraw an open request; the version goes back to draft. By its requester, or an admin (`tenants:settings`)", "tags": ["workflow-definitions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "maxLength": 2000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "kind": { "type": "string", "enum": ["workflow", "rule", "rule_set", "collection_flow"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "requestedBy": { "type": "string", "minLength": 1 }, "requestedAt": { "type": "string", "format": "date-time" }, "comment": { "type": ["string", "null"] }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "type": "string", "enum": ["approved", "rejected", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "kind", "key", "version", "requestedBy", "requestedAt" ], "additionalProperties": false }, "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": ["string", "null"] }, "updatedBy": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["manual", "subject.created", "event"] }, "status": { "type": "string", "enum": ["draft", "pending_approval", "published", "archived"] }, "definition": { "type": "object", "properties": { "entryStepId": { "type": "string", "minLength": 1 }, "steps": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["evaluate_rules"] }, "ruleKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "ruleSetKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "outputKey": { "default": "rules", "type": "string" } }, "required": ["id", "type", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["call_app"] }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "action": { "type": "string", "minLength": 1 }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "inputMapping": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "outputKey": { "type": "string", "minLength": 1 }, "retry": { "type": "object", "properties": { "maximumAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "initialIntervalSeconds": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "type", "app", "action", "input", "inputMapping", "outputKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["wait_for_collection"] }, "flowKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "outputKey": { "default": "submission", "type": "string" } }, "required": ["id", "type", "flowKey", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["create_case"] }, "caseType": { "type": "string", "minLength": 1 }, "priority": { "default": "medium", "type": "string", "enum": ["low", "medium", "high", "critical"] }, "slaHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "priorityFrom": { "type": "string", "minLength": 1 }, "queueFrom": { "type": "string", "minLength": 1 }, "outputKey": { "default": "manualDecision", "type": "string" } }, "required": ["id", "type", "caseType", "priority", "outputKey"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["emit_decision"] }, "mode": { "default": "from_rules", "type": "string", "enum": ["from_rules", "fixed"] }, "rulesKey": { "default": "rules", "type": "string" }, "manualDecisionKey": { "default": "manualDecision", "type": "string" }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "required": [ "id", "type", "mode", "rulesKey", "manualDecisionKey" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "next": { "type": "string" }, "type": { "type": "string", "enum": ["branch"] }, "conditions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": {} }, "required": ["path", "op"], "additionalProperties": false }, "next": { "type": "string", "minLength": 1 } }, "required": ["when", "next"], "additionalProperties": false } }, "default": { "type": "string", "minLength": 1 } }, "required": ["id", "type", "conditions", "default"], "additionalProperties": false } ] } }, "ui": { "type": "object", "properties": { "positions": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": ["x", "y"], "additionalProperties": false } } }, "required": ["positions"], "additionalProperties": false } }, "required": ["entryStepId", "steps"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "key", "version", "name", "trigger", "status", "definition" ], "additionalProperties": false } }, "required": ["approval", "definition"], "additionalProperties": false } } } } } } }, "/workflow-runs": { "post": { "summary": "Start a run of the published definition for a subject", "tags": ["workflow-runs"], "description": "`trigger` records what started the run: `api` (the default) or `console` (a person in the admin console); `correlationId` is your own id for it (an order or application number, at most 200 characters), returned on the run and matched exactly by `search`. Without `runs:context` every context value is `[redacted]` (keys kept): the context holds signed collection links and subject data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "trigger": { "type": "string", "enum": ["api", "console"] }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["definitionKey", "subjectId"] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger" ], "additionalProperties": false } } } } } }, "get": { "summary": "List the tenant's runs, or one subject's, newest first, with the total", "tags": ["workflow-runs"], "description": "Newest first by `startedAt`. Every filter is optional: `subjectId`, `status`, `outcome` and `trigger` (`api`, `console`, `replay`; repeated params), `definitionKey`, and `from`/`to`, inclusive bounds on `startedAt`. `outcome` is the outcome of the decision the run emitted, so only completed runs match it. `search` matches a prefix of the run id in its hyphenated form, a correlation id exactly, or the subject the way `GET /subjects?search=` does (external id exactly or as a prefix, `data.name` or `data.legalName` as a prefix). Each item adds `durationMs` (`finishedAt`, or the time of the request for an active run, minus `startedAt`) and `outcome` (`null` until the run emits a decision). `total` counts the matches, ignoring `limit` and `offset`, and stops at 100,000: `totalIsEstimate` is `true` when it did. `expand=subject` adds the subject as `{ id, externalId, kind, country, displayName }`, read in one extra query; the name is not masked and nothing else from the subject data is returned. Without `runs:context` every context value is `[redacted]` (keys kept): the context holds signed collection links and subject data.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] } }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "query", "name": "definitionKey", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "in": "query", "name": "outcome", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["api", "console", "replay"] } }, "in": "query", "name": "trigger", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["subject"] } }, "in": "query", "name": "expand", "required": false }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] }, "durationMs": { "type": "number", "minimum": 0 }, "outcome": { "anyOf": [ { "type": "string", "enum": ["approve", "reject", "manual_review"] }, { "type": "null" } ] }, "subject": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "externalId": { "type": ["string", "null"] }, "kind": { "type": "string", "enum": ["merchant", "seller", "user"] }, "country": { "type": "string" }, "displayName": { "type": "string" } }, "required": ["id", "kind", "displayName"], "additionalProperties": false } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger", "durationMs", "outcome" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/workflow-runs/summary": { "get": { "summary": "Counts per status, the p95 duration and the automated share of matching runs", "tags": ["workflow-runs"], "description": "The runs `GET /workflow-runs` lists for the same filters (`subjectId`, `status`, `outcome`, `trigger`, `definitionKey`, `search`, and `from`/`to` on `startedAt`): `total`, `byStatus` with every status (zero when no run has it), `p95DurationMs`, the 95th percentile (`percentile_cont`) of `finishedAt - startedAt` over the runs that have finished (`null` when none has), and `autoDecidedPct`, the share of the runs with a decision decided without a reviewer (`null` when none has one). Computed in SQL on every request.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "query", "name": "subjectId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] } }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "in": "query", "name": "definitionKey", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["approve", "reject", "manual_review"] } }, "in": "query", "name": "outcome", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "enum": ["api", "console", "replay"] } }, "in": "query", "name": "trigger", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byStatus": { "type": "object", "propertyNames": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "p95DurationMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "autoDecidedPct": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": ["total", "byStatus", "p95DurationMs", "autoDecidedPct"], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}": { "get": { "summary": "Get a run", "tags": ["workflow-runs"], "description": "Without `runs:context` every context value is `[redacted]` (keys kept): the context holds signed collection links and subject data.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger" ], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}/cancel": { "post": { "summary": "Cancel an active run", "tags": ["workflow-runs"], "description": "Asks Temporal to cancel the run's workflow and marks the run `cancelled` with `error` `cancelled: `. Its open cases close with reason `run_cancelled` (no decision is taken) and its forms still in progress, its own and the follow-ups of requests for information, are withdrawn. Writes `workflow.run.cancelled` with the reason and what was closed, plus a `case.closed` or `collection.submission.withdrawn` event for each. 409 `run_finished` once the run has completed, failed or been cancelled; 503 without Temporal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": ["reason"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger" ], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}/evaluations": { "get": { "summary": "List the rule evaluation snapshots a run recorded (in evaluation order)", "tags": ["workflow-runs"], "description": "Without `runs:context` every value of `data` and of each result's `details` is `[redacted]` (keys kept).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ruleKeys": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "results": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": "number" }, "evaluatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "workflowRunId", "stepId", "subjectId", "ruleKeys", "data", "results", "outcome", "riskScore", "evaluatedAt" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}/history": { "get": { "summary": "The run's Temporal event history (admin only)", "tags": ["workflow-runs"], "description": "Proto JSON (`temporal.api.history.v1.History`) for replaying the run against a new worker bundle with `node dist/replay.js` (docs/performance.md). Admin only: event payloads carry the unredacted run context. 409 when Temporal is not configured.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": {} } }, "required": ["events"], "additionalProperties": {} } } } } } } }, "/workflow-runs/{id}/related": { "get": { "summary": "What the run produced and the runs linked to it", "tags": ["workflow-runs"], "description": "`cases` (the cases the run created, oldest first) and `decision` (the one it emitted) for callers with `cases:read`, empty and `null` otherwise; `replayOf`, the run this one replayed and the step it started at; `replays`, the runs that replayed this one (oldest first, at most 100); `traceUrl`, the trace of the run's start in the tracing backend, for callers with `ops:read` when `TRACE_URL_TEMPLATE` is set and the start was traced, `null` otherwise; `deliveries`, the webhook deliveries of the run's events (its decision, cases and end), newest first and at most 50, for callers with `webhooks:read`. Case context and rule result details are redacted as on the case and decision routes.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": ["open", "in_review", "decided", "closed"] }, "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "assigneeId": { "type": ["string", "null"] }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaBreachedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "slaWarnPct": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 99 }, { "type": "null" } ] }, "firstResponseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedReason": { "type": ["string", "null"] }, "infoRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "queue": { "type": ["string", "null"] }, "slaState": { "type": "string", "enum": ["none", "ok", "due_soon", "breached"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "subjectId", "type", "status", "priority", "context", "slaState" ], "additionalProperties": false } }, "decision": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "caseId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": ["approve", "reject", "manual_review"] }, "riskScore": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "ruleKey": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "source": { "type": "string", "enum": ["automated", "manual"] }, "decidedBy": { "type": ["string", "null"] }, "ruleResults": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "severity": { "type": "string", "enum": ["info", "warn", "block"] }, "weight": { "type": ["number", "null"] }, "outcome": { "type": "string", "enum": ["pass", "fail", "error", "skipped"] }, "score": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } }, "details": {}, "durationMs": { "type": "number", "minimum": 0 }, "shadow": { "type": "boolean" } }, "required": [ "ruleId", "ruleKey", "ruleVersion", "severity", "outcome", "reasons", "durationMs" ], "additionalProperties": false } }, "ruleSetKey": { "type": ["string", "null"] }, "ruleSetVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenantId", "subjectId", "outcome", "reasons", "source", "ruleResults", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "startedAt": { "type": "string", "format": "date-time" }, "stepId": { "type": ["string", "null"] } }, "required": ["id", "status", "startedAt", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "replays": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "startedAt": { "type": "string", "format": "date-time" }, "stepId": { "type": ["string", "null"] } }, "required": ["id", "status", "startedAt", "stepId"], "additionalProperties": false } }, "traceUrl": { "type": ["string", "null"] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "endpointId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "eventId": { "type": "string" }, "event": { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "workflowRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["pending", "delivered", "failed", "exhausted"] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastResponseCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastError": { "type": ["string", "null"] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "enum": [ "decision.created", "case.created", "case.assigned", "case.decided", "case.closed", "case.sla.breached", "run.completed", "run.failed", "approval.requested", "approval.decided", "app.circuit.opened", "submission.link_requested" ] }, { "type": "string", "enum": ["ping"] } ] }, "occurredAt": { "type": "string", "format": "date-time" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "required": ["type", "id"], "additionalProperties": false }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "occurredAt", "tenantId", "resource", "data" ], "additionalProperties": false } }, "required": [ "id", "endpointId", "eventId", "event", "resource", "workflowRunId", "status", "attempts", "lastResponseCode", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "payload" ], "additionalProperties": false } } }, "required": [ "cases", "decision", "replayOf", "replays", "traceUrl", "deliveries" ], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}/replay": { "post": { "summary": "Replay a finished run from one of its steps", "tags": ["workflow-runs"], "description": "Starts a new run (`trigger` `replay`) of the definition version the run executed, for the same subject and correlation id, at `fromStepId` with the context the run had when it last started that step, as its step trace recorded it; the steps after it run again (a form is asked for again, a case is opened again, a decision is emitted for the new run). The new run carries `replayOf` and is listed under `replays` on the original. 409 `run_active` until the run has finished (cancel it first), `step_not_reached` when its trace has no visit of the step; 503 without Temporal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromStepId": { "type": "string", "minLength": 1 } }, "required": ["fromStepId"] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "tenantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "definitionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "definitionKey": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "subjectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "temporalWorkflowId": { "type": "string" }, "temporalRunId": { "type": ["string", "null"] }, "status": { "type": "string", "enum": [ "running", "waiting_collection", "waiting_manual", "waiting_callback", "completed", "failed", "cancelled" ] }, "currentStepId": { "type": ["string", "null"] }, "context": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "decisionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "trigger": { "default": "api", "type": "string", "enum": ["api", "console", "replay"] }, "correlationId": { "type": ["string", "null"] }, "replayOf": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" } }, "required": ["runId", "stepId"], "additionalProperties": false }, { "type": "null" } ] }, "traceId": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "createdAt", "updatedAt", "definitionId", "definitionKey", "definitionVersion", "subjectId", "temporalWorkflowId", "status", "context", "startedAt", "trigger" ], "additionalProperties": false } } } } } } }, "/workflow-runs/{id}/steps": { "get": { "summary": "The run's step trace: every visit of a step, in the order they started", "tags": ["workflow-runs"], "description": "One item per visit the worker traced: a step runs once per visit (`visit` counts the times a loop brought the run back) and, when a request for information repeats the checks, once more per round (`round` 2 and up). Each item has its `status` (`running`, `waiting`, `completed`, `failed`, `cancelled`), `startedAt`, `finishedAt`, `durationMs` (until the request while open), a one-line `summary`, the step `input` and `output`, the `error` of a failed visit, and `refs` to the rows it wrote: `evaluationId`, `invocationId` (the newest attempt), `callbackId`, `submissionId`, `caseId`, `decisionId`. Without `runs:context` the values of `input` and `output` are `[redacted]` (keys kept). At most 500 items; `total` counts them all. Runs started before the trace existed have none.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "stepId": { "type": "string" }, "stepType": { "type": "string" }, "visit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "round": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["running", "waiting", "completed", "failed", "cancelled"] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0 }, "summary": { "type": ["string", "null"] }, "input": {}, "output": {}, "error": { "type": ["string", "null"] }, "refs": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "invocationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "callbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "submissionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "caseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "decisionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, "additionalProperties": false } }, "required": [ "id", "runId", "stepId", "stepType", "visit", "round", "status", "startedAt", "durationMs", "summary", "input", "output", "refs" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows matching the filters, ignoring paging" }, "totalIsEstimate": { "description": "On the lists that stop counting at 100,000: `true` when the count stopped there, so at least `total` rows match", "type": "boolean" } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/workflow-step-types": { "get": { "summary": "Workflow step types with their config JSON Schemas and editor hints", "tags": ["workflow-definitions"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "configSchema": {}, "dataPaths": { "default": [], "type": "array", "items": { "type": "string" } }, "outputs": { "default": [], "type": "array", "items": { "type": "string" } }, "terminal": { "default": false, "type": "boolean" }, "uiHints": { "type": "object", "properties": { "fieldOrder": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "help": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "pickers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "type", "title", "description", "configSchema", "dataPaths", "outputs", "terminal" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } } }, "security": [ { "bearer": [] } ] }