{ "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": "support@actanomos.com" } }, "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`, `install` (the name the call used) and `installId` narrow the list; `total` counts every match, ignoring `limit` and `offset`. Each session names its install (`installId`, `installName`) and 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": "install", "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": "installId", "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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", "installId", "installName", "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-install-changes": { "get": { "summary": "Saves of the tenant's installs held for an approval", "tags": ["apps"], "description": "`status=open` (the default) lists the changes waiting for a decision, oldest first; `status=decided` the approved, rejected and withdrawn ones, newest first (a rejected or withdrawn new install's change goes with its install). `install` narrows the list to one install's changes. Each change carries the state the save asked for (version, config, `enabled`, `hosts`), `hostsAdded` (what the approval is for), `newInstall`, and `approvalSettings`, the settings in force when it was requested, which its decision follows. `origin` is `save` for an administrator's save that adds hosts while the tenant requires approvals, `auto_upgrade` for an automatic upgrade (requested by `system`, approval required and four-eyes off whatever the tenant's settings) whose target adds hosts or capabilities: `needsAdded` (such as `documents`, a token to read the tenant's documents on every call) and `handlesAdded` (`webhook`, `handoff`) name the capabilities. A rejected automatic upgrade is never asked again for that version. An administrator other than the requester (with four-eyes on) decides it with `POST /app-installs/:install/changes/:id/approve` or `/reject`; its requester can `/withdraw` it.", "parameters": [ { "schema": { "default": "open", "type": "string", "enum": ["open", "decided"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "query", "name": "install", "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": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/app-installs": { "get": { "summary": "The tenant's installs by name, optionally of one app", "tags": ["apps"], "description": "`app` narrows the list to the installs of one catalogue app. Each install carries its version unfolded, `requiredSecrets` (the secrets a call needs under its config), `storedSecrets`, `missingSecrets` (required and not stored), `updateAvailable` (a published version of the same publisher has a higher number; a prerelease counts only for an install that runs a prerelease), `webhookUrl` (where its vendor sends webhooks; `null` when it receives none: its version handles no webhooks, or leaves where a webhook names its session to the install's config, which says nothing yet), `pendingChange` (a save waiting for an approval; `null` without one), `aliases` (the former names it still answers to) and, for an install that upgrades automatically (`autoUpgrade` `compatible`), `upgrade`: the version the platform moves it to next (`rollback` when that is below a withdrawn or blocked version it runs), what the move adds and what it waits for (`waitingFor`: `approval`, `secrets`, `config`, `actions` or `declined`; `null` when the next sweep moves it). `circuit` is its circuit breaker, one per install shared by every worker: its `state`, the vendor's outages in a row (`failures`) and since when (`since`, `null` for one that never moved), with the install's own `settings` (`null` for the deployment's) and the deployment's `defaults` (`PUT /app-installs/:install/circuit`). 503 `apps_unavailable` when the deployment runs no apps.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "query", "name": "app", "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})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } }, "post": { "summary": "Install a version of an app under a name of its own", "tags": ["apps"], "description": "An app can be installed several times, e.g. once per vendor account: `name` is the install's own name, unique in the tenant among its installs' names and the former names they keep as aliases; `call_app` steps and `app` rules name it, and a rename (`POST /app-installs/:install/rename`) changes it. `versionId` is a published version the tenant sees (a withdrawn one cannot be newly installed) and picks the app; `config` is validated against that version's schema (400 `validation_error` with the issues). The install's hosts are the version's `hosts` plus the exact host of each URL its config holds where the version's `hostsFromConfig` points (`installHosts`): its hostname, with `:port` when the URL names a port that is not the scheme's default (`api.vendor.example:8443`). A URL is https, without credentials or a wildcard, names no IP address or `localhost` and none of this deployment's own hosts, at any port, and no port browsers refuse (the bad ports of the Fetch standard, such as 22 or 25) nor an explicit default (`:443`); with `APP_RUNNER_ALLOW_PRIVATE_NETWORKS`, http, `localhost` and IPv4 addresses pass. A URL that breaks a rule, a malformed secret variable (its `stepPlaces`, the places a step may use it, are some of `path`, `query`, `headers` and `body`, and only a secret variable lists any) or a `{{secret:NAME}}` naming no declared secret is a 400 `validation_error` with the issues at their pointers. A secret variable a step may use is required like one the config uses, and the audit event records each such variable's places (`secretPlaces`). Every host the save adds to the install's must be listed in `approveHosts`, or the save is refused with 409 `hosts_not_approved` whose `details.added` lists them. A save that adds hosts while the tenant requires approvals for apps (`approvals.required`, with `requiredFor` unset or including `app`) waits for another administrator: 202 with the `change` and the `install` as it serves meanwhile; a newer save of the install withdraws the change (`superseded`). Other saves apply at once; one that asks `enabled: true` while a secret its config requires (`requiredSecrets`) has no stored value is refused with 409 `install_not_configured`, while a held save keeps `enabled` for the approval, which switches the install on only if those secrets are stored by then. `autoUpgrade` `compatible` (with `apps:write`, for an install of a platform app only: 400 for a tenant's app) lets the platform move the install within its version's compatible range (the same major from 1.0.0 on, the same minor on 0.x): the move is checked like a save, waits for an approval as a change of origin `auto_upgrade` when it adds hosts or capabilities, and waits for the secrets, config or actions it lacks (the install's `upgrade` says what). While it is on, a save may not move the install to a lower version (400) unless the same save turns it off; the version the last automatic move left (`upgradedFromVersionId`) may be chosen again, and kept by later saves, even when withdrawn, never when blocked. A save of an opted-in install runs that move at once when nothing stops it, before the answer. Under `APP_SIGNATURES=required` a tenant's version is installed or moved to only with provenance the operator's policy trusts (409 `provenance_required`). The save's event records whether calls through the saved state read the tenant's documents (`readsDocuments`: the version needs `documents` and, when it puts them behind a switch, `documentsFromConfig`, the config holds `true` there) and receive webhooks (`receivesWebhooks`). Documents never hold a save for an approval, nor keep going while one waits: a held save after which calls would read none (its config switches them off, or its version reads none) switches them off at once in the config the install serves with, while one that turns them on waits with the hosts it adds. A save after which the stored install's calls read them, or no longer do, is also audited as `app.install.documents.enabled` or `.disabled`, with the hosts they may go to. A new install has no secrets yet, so one whose config requires any starts disabled: store them, then enable it. A held new install is stored disabled and without hosts until the change is approved, so its secrets can be stored meanwhile; rejecting or withdrawing the change removes it. 409 `install_name_taken` for a name the tenant already uses, 409 `install_limit_reached` at 50 installs, 409 `conflict` for a version that is not published, 409 `app_blocked` for a module the operator blocked. `details.aliasOf` of `install_name_taken` names the install a former name belongs to. Audited as `app.installed`, or `app.install.change.requested` when held.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "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": { "default": true, "type": "boolean" }, "config": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "approveHosts": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "comment": { "type": "string", "maxLength": 2000 }, "autoUpgrade": { "default": "off", "type": "string", "enum": ["off", "compatible"] } }, "required": ["name", "versionId"] } } } }, "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})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": ["approval", "secrets", "config", "actions", "declined"] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "install": { "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, "change": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false } }, "required": ["install", "change"], "additionalProperties": false } } } } } } }, "/app-installs/{install}": { "get": { "summary": "One install, with its version, secrets, webhook URL and pending change", "tags": ["apps"], "description": "As `GET /app-installs` lists it. 404 `unknown_install` when the tenant has no install of that name; a former name an install keeps as an alias answers it with `details.renamedTo`, the name to use.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": ["approval", "secrets", "config", "actions", "declined"] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } } } } }, "put": { "summary": "Configure an install, switch it on or off, or move it to another version", "tags": ["apps"], "description": "Points the install at `versionId`, a published version of the same app (400 `validation_error` for another app's), and validates `config` against that version's schema (400 with the issues). The app never changes, and the name only through `POST /app-installs/:install/rename`. `autoUpgrade` left out keeps the install's. The install's hosts are the version's `hosts` plus the exact host of each URL its config holds where the version's `hostsFromConfig` points (`installHosts`): its hostname, with `:port` when the URL names a port that is not the scheme's default (`api.vendor.example:8443`). A URL is https, without credentials or a wildcard, names no IP address or `localhost` and none of this deployment's own hosts, at any port, and no port browsers refuse (the bad ports of the Fetch standard, such as 22 or 25) nor an explicit default (`:443`); with `APP_RUNNER_ALLOW_PRIVATE_NETWORKS`, http, `localhost` and IPv4 addresses pass. A URL that breaks a rule, a malformed secret variable (its `stepPlaces`, the places a step may use it, are some of `path`, `query`, `headers` and `body`, and only a secret variable lists any) or a `{{secret:NAME}}` naming no declared secret is a 400 `validation_error` with the issues at their pointers. A secret variable a step may use is required like one the config uses, and the audit event records each such variable's places (`secretPlaces`). Every host the save adds to the install's must be listed in `approveHosts`, or the save is refused with 409 `hosts_not_approved` whose `details.added` lists them. A save that adds hosts while the tenant requires approvals for apps (`approvals.required`, with `requiredFor` unset or including `app`) waits for another administrator: 202 with the `change` and the `install` as it serves meanwhile; a newer save of the install withdraws the change (`superseded`). Other saves apply at once; one that asks `enabled: true` while a secret its config requires (`requiredSecrets`) has no stored value is refused with 409 `install_not_configured`, while a held save keeps `enabled` for the approval, which switches the install on only if those secrets are stored by then. `autoUpgrade` `compatible` (with `apps:write`, for an install of a platform app only: 400 for a tenant's app) lets the platform move the install within its version's compatible range (the same major from 1.0.0 on, the same minor on 0.x): the move is checked like a save, waits for an approval as a change of origin `auto_upgrade` when it adds hosts or capabilities, and waits for the secrets, config or actions it lacks (the install's `upgrade` says what). While it is on, a save may not move the install to a lower version (400) unless the same save turns it off; the version the last automatic move left (`upgradedFromVersionId`) may be chosen again, and kept by later saves, even when withdrawn, never when blocked. A save of an opted-in install runs that move at once when nothing stops it, before the answer. Under `APP_SIGNATURES=required` a tenant's version is installed or moved to only with provenance the operator's policy trusts (409 `provenance_required`). The save's event records whether calls through the saved state read the tenant's documents (`readsDocuments`: the version needs `documents` and, when it puts them behind a switch, `documentsFromConfig`, the config holds `true` there) and receive webhooks (`receivesWebhooks`). Documents never hold a save for an approval, nor keep going while one waits: a held save after which calls would read none (its config switches them off, or its version reads none) switches them off at once in the config the install serves with, while one that turns them on waits with the hosts it adds. A save after which the stored install's calls read them, or no longer do, is also audited as `app.install.documents.enabled` or `.disabled`, with the hosts they may go to. While a change waits, the install serves as it is: runs, test calls and webhooks reach only its approved hosts; a held save that switches the install off, or its documents, applies that at once. Removing hosts, and changes to the version, config or secrets that add none, apply at once. A save that only switches an enabled install off (the same version and config) is never refused: it keeps the approved hosts without checking the version, its module or the URLs of its config again. Moving the install to another version or changing its config, by a save or an approved change, clears its cached values (audited as `app.cache.cleared` with `reason` `version` or `config` when a live value went); the same config saved again keeps them. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name), 409 `conflict` for a version that is not published, 409 `app_blocked` for a module the operator blocked. Audited as `app.configured`, or `app.install.change.requested` when held.", "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": {} }, "approveHosts": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "comment": { "type": "string", "maxLength": 2000 }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] } }, "required": ["versionId"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": ["approval", "secrets", "config", "actions", "declined"] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "install": { "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, "change": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false } }, "required": ["install", "change"], "additionalProperties": false } } } } } }, "delete": { "summary": "Remove an install: it goes with its secrets, cached values, aliases, circuit and changes, its history stays", "tags": ["apps"], "description": "The app stays in the catalogue and its other installs are untouched; the name and the former names it kept as aliases are free again. 409 `install_in_use` while runs wait on the install's callbacks, unless `force=true` fails those callbacks (each run ends its wait with `install_removed`). Its invocations, callbacks and webhook events are kept; its webhook URL answers 404 `unknown_install` from then on. Audited as `app.uninstalled` with the callbacks failed and the secrets removed. 404 `unknown_install` without an install of that name.", "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": "install", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/app-installs/{install}/aliases/{alias}": { "delete": { "summary": "Stop an install answering to a former name, freeing the name", "tags": ["apps"], "description": "409 `alias_in_use` (`details.definitions`, `details.runs`) while published definitions or runs in flight whose workflow version calls the alias still name it, unless `force=true`: their steps and rules then fail with `unknown_install`, and so does replaying a run pinned to a version that calls it. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name), 404 `not_found` when the install keeps no such alias. Audited as `app.install.alias.removed`.", "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": "install", "required": true }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "alias", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/app-installs/{install}/cache": { "get": { "summary": "An install's cached values: their names and when each expires, never a value", "tags": ["apps"], "description": "What the install's module keeps between its calls (`ctx.cache`, the `cache` host function), such as a vendor's token: sealed in the tenant's store with the deployment key (`SECRET_STORE_KEY`), bound to the install like its secrets, and handed only to the install's own calls, its runs', test calls', webhooks' and hand-offs'. Each live value's `name`, when it `expiresAt` (a day after it was set at most), when a call last wrote it (`updatedAt`) and its `sizeBytes` as UTF-8; never the value, which no answer, log or record shows (a call's redactions mark it `[cache:NAME]`). `limits` is the deployment's budget per install (`APP_CACHE_ENTRIES` values and `APP_CACHE_TOTAL_BYTES` bytes together): past it, the values written longest ago go. The values are cleared when a secret of the install is stored or revoked, when its config changes or it moves to another version (each audited as `app.cache.cleared` when a live value went), when it is removed, and by hand (`DELETE`). 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["name", "expiresAt", "updatedAt", "sizeBytes"], "additionalProperties": false } }, "limits": { "type": "object", "properties": { "entries": { "type": "integer", "minimum": 1, "maximum": 64 }, "totalBytes": { "type": "integer", "minimum": 8192, "maximum": 524288 } }, "required": ["entries", "totalBytes"], "additionalProperties": false } }, "required": ["items", "limits"], "additionalProperties": false } } } } } }, "delete": { "summary": "Clear an install's cached values", "tags": ["apps"], "description": "Removes every cached value of the install at once: its next calls start without them, and a call that read them before stores nothing of what it changed, so a value is never written back over the clear. Use it after a vendor revoked what the module keeps, such as its token. Audited as `app.cache.cleared` with `reason` `manual` and the live values removed (`entries`), whatever they were. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "204": { "description": "Default Response" } } } }, "/app-installs/{install}/changes/{id}/approve": { "post": { "summary": "Approve a held change of an install and apply it", "tags": ["apps"], "description": "Applies the change's version, config and hosts to the install in one transaction, and its `enabled` only when every secret the config requires is stored by then: otherwise the install is left off and `missingSecrets` says why (store them, then save it with `enabled: true`). With four-eyes on when the change was requested (`approvalSettings.fourEyes`), never by its requester, whatever the settings say now: 403 `four_eyes`. The version and the config are checked again: 409 `conflict` for a version no longer published (except the version the install's last automatic upgrade left, which a save may move back to withdrawn), 409 `app_blocked` for a module the operator blocked, 400 `validation_error` for a config that no longer holds, 409 `conflict` when its URLs no longer give the hosts asked for. 409 `install_changed` when the install was saved since the change was requested, 409 `conflict` for a decided change, 404 for a change of another install. Under `APP_SIGNATURES=required`, 409 `provenance_required` for a tenant's version the operator's policy does not trust. Audited as `app.install.change.decided`; an automatic upgrade's change that moves the install is also audited as `app.install.upgraded` (`automatic` false), a change after which the install's calls read the tenant's documents, or no longer do (`installReadsDocuments`), as `app.install.documents.enabled` or `.disabled`, and an install that upgrades automatically then moves on when a newer move is due.", "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": "install", "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": { "change": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["change", "install"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/changes/{id}/reject": { "post": { "summary": "Reject a held change of an install", "tags": ["apps"], "description": "The install keeps serving as it is. A new install's change takes the install with it, and its secrets: `install` is `null` then. 409 `conflict` for a decided change, 404 for a change of another install. Audited as `app.install.change.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": "install", "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": { "change": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["change", "install"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/changes/{id}/withdraw": { "post": { "summary": "Withdraw a held change of an install: by its requester, or an admin", "tags": ["apps"], "description": "As a rejection, by whoever requested it or an admin (`tenants:settings`; 403 `not_requester` for anyone else): the install keeps serving as it is, and a new install's change takes the install and its secrets with it (`install` is `null` then). 409 `conflict` for a decided change, 404 for a change of another install. Audited as `app.install.change.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": "install", "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": { "change": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["change", "install"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/circuit": { "put": { "summary": "Set an install's circuit breaker: the outages that open it and how long it stays open", "tags": ["apps"], "description": "`failureThreshold` (1 to 100) is how many of the vendor's outages in a row (errors the app calls retryable, and timeouts) open the install's circuit; `openSeconds` (5 to 3600) how long an open circuit refuses calls, without reaching the runner, before one trial call goes out. Both are required; `null` takes the deployment's (`APP_CIRCUIT_FAILURE_THRESHOLD`, `APP_CIRCUIT_OPEN_SECONDS`), which the answer's `defaults` give. They apply from the next call on every worker; the circuit's state and count are kept. Audited as `app.circuit.configured` with the settings before and after. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/circuit/reset": { "post": { "summary": "Close an install's circuit breaker by hand", "tags": ["apps"], "description": "Closes the install's circuit and clears its count of outages at once, for every worker: its next call goes out. Audited as `app.circuit.reset` with the `state` and the `failures` it cleared, whatever they were. The answer is the closed circuit. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/limits": { "get": { "summary": "An install's budgets and the prices of its actions", "tags": ["apps"], "description": "`budgets` cap the install's `calls`, `http_requests` or `spend` per UTC `day` or `month` (`max`, spend in micros of `currency`); `prices` give what one call of an action costs, in micros (an action without a price costs nothing). Without limits set: no currency, no prices, no budgets, `updatedBy` and `updatedAt` `null`. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "prices": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,99}$" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 1000000000000000 } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": ["calls", "http_requests", "spend"] }, "period": { "type": "string", "enum": ["day", "month"] }, "max": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000000 } }, "required": ["metric", "period", "max"], "additionalProperties": false } }, "updatedBy": { "type": ["string", "null"] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "installId", "currency", "prices", "budgets", "updatedBy", "updatedAt" ], "additionalProperties": false } } } } } }, "put": { "summary": "Set an install's budgets and the prices of its actions", "tags": ["apps"], "description": "Replaces the install's limits with `currency` (ISO 4217, such as `EUR`), `prices` (action -> micros of the currency per call, at most 100) and `budgets` (at most 6, one per metric and period: `calls`, `http_requests` or `spend` per UTC `day` or `month`), each optional. Spend counts each call that succeeded or started its asynchronous work at its action's price. They apply from the next call: a call is refused (429 `app_quota_exceeded`) once the period's use reached a budget, a priced call once its price would pass a spend budget, until the period ends. Enforcement is soft: calls in flight on other workers are not weighed. 400 `validation_error` for a price of an action the install's version does not declare, a price or a spend budget without a currency, or two budgets of one metric and period. 409 `conflict` for a currency other than the one this UTC month's spend through the install is in: what it spent stays in that currency, so another applies from a month that spends nothing. Audited as `app.limits.updated`. 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "default": null, "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "prices": { "default": {}, "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,99}$" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 1000000000000000 } }, "budgets": { "default": [], "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": ["calls", "http_requests", "spend"] }, "period": { "type": "string", "enum": ["day", "month"] }, "max": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000000 } }, "required": ["metric", "period", "max"] } } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "prices": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,99}$" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 1000000000000000 } }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": ["calls", "http_requests", "spend"] }, "period": { "type": "string", "enum": ["day", "month"] }, "max": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000000 } }, "required": ["metric", "period", "max"], "additionalProperties": false } }, "updatedBy": { "type": ["string", "null"] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "installId", "currency", "prices", "budgets", "updatedBy", "updatedAt" ], "additionalProperties": false } } } } } } }, "/app-installs/{install}/rename": { "post": { "summary": "Rename an install, keeping its former name as an alias by default", "tags": ["apps"], "description": "The install takes `name` and keeps its id, so its secrets, circuit, callbacks, changes and webhook URL stay with it. With `keepAlias` (the default) the former name stays an alias of the install, at most 5 per install (409 `alias_limit_reached` beyond: remove one with `DELETE /app-installs/:install/aliases/:alias`): runs in flight, definitions that still name it and old links keep reaching the install, and the editors warn `install_renamed` where a step or rule names it. Without `keepAlias` the former name is free again, which is refused with 409 `install_in_use` (`details.definitions`, `details.runs`) while published definitions or runs in flight still call it. Renaming an install to one of its own aliases takes that alias back. `rewrite` updates the published workflows and `app` rules that call the install by any of its names: `drafts` (needs `definitions:write`) writes a new draft of each calling the new name, `publish` (also `definitions:publish`) publishes each, or requests its approval where the tenant requires approvals for that kind; a definition with a version newer than its published one is skipped (`skipped`, `draft_pending`), and one whose references no longer resolve stays a draft. Names and aliases share the tenant's namespace: 409 `install_name_taken` for a name another install has or keeps (`details.aliasOf`). 404 `unknown_install` without an install of that name (with `details.renamedTo` for a former name). Audited as `app.install.renamed`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "keepAlias": { "default": true, "type": "boolean" }, "rewrite": { "default": "none", "type": "string", "enum": ["none", "drafts", "publish"] } }, "required": ["name"] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "install": { "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}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false }, "alias": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, { "type": "null" } ] }, "definitions": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule"] }, "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 } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["workflow", "rule"] }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "enum": ["draft_pending"] } }, "required": ["kind", "key", "version", "reason"], "additionalProperties": false } } }, "required": ["install", "alias", "definitions", "skipped"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/secrets/{secret}": { "post": { "summary": "Store a secret of an install", "tags": ["apps"], "description": "Seals `value` with the deployment key (`SECRET_STORE_KEY`, AES-256-GCM) in the tenant's secret store, bound to the install, replacing the previous value of that name; the value is never returned or logged, and no other install, even of the same app, can open it. The install's `missingSecrets` loses the name at once. A secret is one the installed version declares, or a secret variable of the install's config (the version's `secretsFromConfig`); a published version of its app the install could move to, the version its last automatic upgrade left (which it may move back to, even withdrawn) and a change waiting for an approval add theirs, so the secrets come before the move or the approval and the install stays enabled throughout. While a new install waits for its first approval, its secrets are stored on it. Storing one clears the install's cached values, so nothing a call kept from the former value is read again (audited as `app.cache.cleared` with `reason` `secret` when a live value went). Audited as `app.secret.stored` with the install, its app and the secret name. For an install that upgrades automatically, a move that waited for the secret applies, or opens its change, before the answer. 400 for any other name, 404 `unknown_install` without an install of that name (or once it is removed; with `details.renamedTo` for a former name), 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": "install", "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 install", "tags": ["apps"], "description": "The name leaves the install's `storedSecrets`, and joins its `missingSecrets` when its config requires it: its calls are then refused with 409 `install_not_configured` until a value is stored, and an enabled install is left enabled. The install's cached values are cleared (`app.cache.cleared`, `reason` `secret`, when a live value went). Audited as `app.secret.revoked`. 404 `unknown_install` without an install of that name, 404 `not_found` without a stored value of that name.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "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" } } } }, "/app-installs/{install}/test": { "post": { "summary": "Call one action through an install once with the install's configuration, as a test", "tags": ["apps"], "description": "Runs the action on the installed version with the install's configuration, the secrets that configuration requires (`requiredSecrets`, no others), its approved hosts and its live cached values (`ctx.cache`), enabled or not, once: no retries, no circuit breaker, nothing recorded in `app_invocations`. What the call changes of the cached values is kept, whatever it answers, as for a run's call. A change waiting for an approval plays no part. It counts as a call of the install (`GET /apps/metering`) once it reached the runner, with the HTTP requests it made and, when it succeeded or started its asynchronous work, its action's price, and is weighed first against the operator's quotas of the tenant and the install's budgets: 429 `app_quota_exceeded` (`details`: the limit's `scope`, `metric`, `period`, `max`, `used` and `resetsAt`) when the period's use reached one, the first refusal of each limit and period audited as `app.quota.exceeded`. The input goes to the module as given: text in it that reads like a secret placeholder stays text, since the host fills only the placeholders carrying the tag it draws for each call. The module reads the tenant's documents (`document_read`, a document as a request body or a part) only while the install's calls read them (`installReadsDocuments`: its version needs `documents` and, with a documents switch, `documentsFromConfig`, the install's config turns it on) and only for a caller who also holds `documents:read`: a test call has no subject, so it may name any clean document of the tenant. Otherwise the host refuses those reads, and the call answers the module's error. 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 `unknown_install` without an install of that name, 409 `app_blocked` for a module the operator blocked (with the operator's `reason` in `details`), 409 `install_not_configured` when a required secret has no stored value, 503 `secret_store_unavailable` when there is no key to open the secrets.", "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": "install", "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 }, "reusedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ai": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["requests", "inputTokens", "outputTokens"], "additionalProperties": false } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false } }, "required": ["status", "durationMs"], "additionalProperties": false } } } } } } }, "/app-installs/{install}/usage": { "get": { "summary": "The published definitions that name an install, by its name or an alias", "tags": ["apps"], "description": "The published workflows with a `call_app` step naming the install and the published `app` rules naming it, as their own install or as their fallback, by its name or one of the former names it keeps as aliases, each with the actions it calls and `calledAs`, the name it calls the install by (a definition that uses two of its names is listed once per name). Answered for any name, installed or not: a definition can name an install before it exists. A former name an install keeps as an alias answers 404 `unknown_install` with `details.renamedTo`. An install in use can still be removed: its steps then fail with `unknown_install`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "in": "path", "name": "install", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "installName": { "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" } }, "calledAs": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "required": ["kind", "key", "version", "status", "actions", "calledAs"], "additionalProperties": false } } }, "required": ["installName", "definitions"], "additionalProperties": false } } } } } } }, "/app-invocations": { "get": { "summary": "App invocations, newest first, filtered, with the total", "tags": ["apps"], "description": "`install` (the name the call used: the install's name then, or a former name it keeps, so a reused name also matches its earlier installs and a renamed install's calls are found by `installId`), `installId` (one install), `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 install it went through (`installId`, and `installName`, the name the call used), the `versionId` the call ran on, which names the app, and what it used at the runner (`usage`); an attempt through a step's or a rule's fallback names the install the call was meant for (`fallbackOf`: its `installId` and the `installName` the call used), which could not answer. Records outlive their install. 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": "install", "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": "installId", "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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 }, "reusedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ai": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["requests", "inputTokens", "outputTokens"], "additionalProperties": false } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] }, "fallbackOf": { "anyOf": [ { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "required": ["installId", "installName"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "installId", "installName", "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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 }, "reusedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ai": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["requests", "inputTokens", "outputTokens"], "additionalProperties": false } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] }, "fallbackOf": { "anyOf": [ { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "required": ["installId", "installName"], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "tenantId", "installId", "installName", "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, each with its installs", "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 highest published version by number (SemVer precedence), a prerelease only when no release is published, or the highest of any status when none is published; `versions` counts the versions the tenant sees. `installs` lists the tenant's installs of the app by name, empty when it has none: each carries its version unfolded, `requiredSecrets` (what its config requires), `storedSecrets` and `missingSecrets` (required and not stored), `updateAvailable` (a published version of the same publisher has a higher number; a prerelease counts only for an install that runs a prerelease), `webhookUrl`, `pendingChange` (a save waiting for an approval), `aliases`, `upgrade` (where an install that upgrades automatically moves next, as `GET /app-installs` describes) and `circuit`. Each version carries its `provenance` (who signed the module, trusted or not under the operator's policy as it is now; `null` when unsigned). `signatures` is the deployment's signature mode (`APP_SIGNATURES`), which says whether an upload must be signed: `off` takes no provenance, `optional` verifies the bundle attached to a version and shows it, `required` publishes, installs and upgrades to a tenant's version only once a signer the operator's policy trusts has signed it. 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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "versions": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "installs": { "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})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": [ "state", "failures", "since", "settings", "defaults" ], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } }, "required": ["name", "publisher", "latest", "versions", "installs"], "additionalProperties": false } }, "signatures": { "type": "string", "enum": ["off", "optional", "required"] } }, "required": ["items", "signatures"], "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", "withdrawn"] }, { "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false } }, "required": ["approval", "version"], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["items", "total"], "additionalProperties": false } } } } } } }, "/apps/health": { "get": { "summary": "Per install, its calls of the last `windowMinutes` (5 to 1440, default 60)", "tags": ["apps"], "description": "Computed over the invocations of the window, one item per install with the catalogue app its calls ran: `calls`, `failures` (`error` or `timeout`), `timeouts`, `p95Ms` (95th percentile of `durationMs` over the finished calls, `null` when every call is pending), `lastInvokedAt` and `lastErrorAt`. Installs without a call in the window are absent from `items`; an install's calls count as one item under its current name, whatever names they were made by (it keeps its former names as aliases after a rename), and a removed install's calls stay apart from a newer install of the same name. No error text is returned: it can quote what the vendor answered about the subject. `circuits` lists the installs whose circuit breaker, one per install shared by every worker, is `open` or `half_open` now, whatever the window, with the outages that opened it (`failures`) and the threshold that applies (`failureThreshold`: the install's own, or the deployment's); `blocked` the installs, by name, whose version the operator blocked (its module, or every version of its app), with the operator's `reason` and when the block was made (`blockedAt`): every call, test call, webhook and hand-off of them fails with `app_blocked` until the operator lifts the block.", "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": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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": [ "installId", "installName", "appName", "calls", "failures", "timeouts", "p95Ms", "lastInvokedAt", "lastErrorAt" ], "additionalProperties": false } }, "circuits": { "type": "array", "items": { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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 }, "failureThreshold": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "installId", "installName", "state", "since", "failures", "failureThreshold" ], "additionalProperties": false } }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "reason": { "type": "string" }, "blockedAt": { "type": "string", "format": "date-time" } }, "required": ["installName", "sha256", "reason", "blockedAt"], "additionalProperties": false } } }, "required": ["windowMinutes", "from", "items", "circuits", "blocked"], "additionalProperties": false } } } } } } }, "/apps/metering": { "get": { "summary": "The tenant's use of its installs over one UTC month, against its quotas and budgets", "tags": ["apps"], "description": "`month` (`YYYY-MM`, this UTC month by default). What counts: `calls`, every attempt of an action that reached the runner (a run's steps and rules, retries included, and test calls; a call the platform refused before the runner, or that the runner refused as busy, does not count), with the `httpRequests` they made; `webhookHandlings` and `handoffs`, the vendor's webhooks and the applicants' hand-offs the installs' modules ran, counted apart and never limited; `spendMicros`, the install's price of each call that succeeded or started its asynchronous work, in micros of the install's `currency` (1.00 is 1000000), the one the month charged it in, a removed install's too. `totals` and `days` add up the tenant's installs, without spend, which adds up per currency; `installs` lists each install with use in the month or a budget, removed ones included (`installed: false`), with its month, its days and its budgets with this period's use (`used`; `reached` once the budget refuses calls, a spend budget once what is left is below the price of one of the install's actions; and `resetsAt`, when the UTC day or month ends). `quotas` are the operator's quotas of the tenant with this period's use: a call is refused once one is used up, as once one of its install's budgets is (429 `app_quota_exceeded`), until the period ends. Spend, the currency and spend budgets are shown with `apps:write` only: `spendMicros` and `currency` are `null` without it. 503 `apps_unavailable` when the deployment runs no apps.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "in": "query", "name": "month", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "totals": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookHandlings": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "handoffs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["calls", "httpRequests", "webhookHandlings", "handoffs"], "additionalProperties": false }, "days": { "type": "array", "items": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookHandlings": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "handoffs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "calls", "httpRequests", "webhookHandlings", "handoffs", "day" ], "additionalProperties": false } }, "installs": { "type": "array", "items": { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "installed": { "type": "boolean" }, "month": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookHandlings": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "handoffs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spendMicros": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "calls", "httpRequests", "webhookHandlings", "handoffs", "spendMicros" ], "additionalProperties": false }, "days": { "type": "array", "items": { "type": "object", "properties": { "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "httpRequests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookHandlings": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "handoffs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spendMicros": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "calls", "httpRequests", "webhookHandlings", "handoffs", "spendMicros", "day" ], "additionalProperties": false } }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "budgets": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": ["calls", "http_requests", "spend"] }, "period": { "type": "string", "enum": ["day", "month"] }, "max": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000000 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "resetsAt": { "type": "string", "format": "date-time" }, "reached": { "type": "boolean" } }, "required": [ "metric", "period", "max", "used", "resetsAt", "reached" ], "additionalProperties": false } } }, "required": [ "installId", "installName", "appName", "installed", "month", "days", "currency", "budgets" ], "additionalProperties": false } }, "quotas": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": ["calls", "http_requests"] }, "period": { "type": "string", "enum": ["day", "month"] }, "max": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000 }, "setBy": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "resetsAt": { "type": "string", "format": "date-time" } }, "required": [ "metric", "period", "max", "setBy", "updatedAt", "used", "resetsAt" ], "additionalProperties": false } } }, "required": ["month", "totals", "days", "installs", "quotas"], "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 unless it carries that maximum already (an SDK build is stored as built, so a signature over the built file holds), stores it by its hash and records the version as `uploaded`: attach its signature with `PUT /apps/:name/versions/:id/provenance`, publish it with `POST /apps/:name/versions/:id/publish`. 409 `app_blocked` when the operator blocked that module or the tenant's app of that name (nothing is stored), 409 `conflict` when the tenant already has that name and version or the name is a platform app's (the platform's apps and the tenant's never share a name). 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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false } }, "required": ["version"], "additionalProperties": false } } } } } } }, "/apps/{name}": { "get": { "summary": "One app of the catalogue with its installs and every version the tenant sees", "tags": ["apps"], "description": "`entry` is the app as `GET /apps` lists it, with its installs; `versions` are as `GET /apps/:name/versions` lists them, the highest number first. `signatures` is the deployment's signature mode (`APP_SIGNATURES`): `off` takes no provenance (`PUT …/provenance` answers 404 `signatures_off`), `optional` verifies and shows what a version carries, `required` publishes, installs and upgrades to a tenant's version only once a signer the operator's policy trusts has signed it. 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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "versions": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "installs": { "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})$" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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})$" }, "autoUpgrade": { "type": "string", "enum": ["off", "compatible"] }, "upgradedFromVersionId": { "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" } ] }, "enabled": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false }, "requiredSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "storedSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "updateAvailable": { "type": "boolean" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "pendingChange": { "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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})$" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "newInstall": { "type": "boolean" }, "installUpdatedAt": { "type": "string", "format": "date-time" }, "approvalSettings": { "type": "object", "properties": { "required": { "type": "boolean" }, "fourEyes": { "type": "boolean" } }, "required": ["required", "fourEyes"], "additionalProperties": false }, "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "installId", "installName", "versionId", "config", "enabled", "hosts", "hostsAdded", "origin", "needsAdded", "handlesAdded", "newInstall", "installUpdatedAt", "approvalSettings", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "upgrade": { "anyOf": [ { "type": "object", "properties": { "target": { "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": "string", "maxLength": 50, "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$" } }, "required": ["id", "version"], "additionalProperties": false }, "rollback": { "type": "boolean" }, "waitingFor": { "anyOf": [ { "type": "string", "enum": [ "approval", "secrets", "config", "actions", "declined" ] }, { "type": "null" } ] }, "hostsAdded": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } }, "missingSecrets": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": ["path", "message"], "additionalProperties": false } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "problem": { "type": "string", "enum": ["missing", "async"] }, "usedBy": { "type": "array", "items": { "type": "string" } } }, "required": ["action", "problem", "usedBy"], "additionalProperties": false } }, "changeId": { "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": [ "target", "rollback", "waitingFor", "hostsAdded", "needsAdded", "handlesAdded", "missingSecrets", "issues", "actions", "changeId" ], "additionalProperties": false }, { "type": "null" } ] }, "circuit": { "type": "object", "properties": { "state": { "type": "string", "enum": ["closed", "open", "half_open"] }, "failures": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "since": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "failureThreshold": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "openSeconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 3600 }, { "type": "null" } ] } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false }, "defaults": { "type": "object", "properties": { "failureThreshold": { "type": "integer", "minimum": 1, "maximum": 100 }, "openSeconds": { "type": "integer", "minimum": 5, "maximum": 3600 } }, "required": ["failureThreshold", "openSeconds"], "additionalProperties": false } }, "required": ["state", "failures", "since", "settings", "defaults"], "additionalProperties": false } }, "required": [ "id", "tenantId", "name", "appName", "versionId", "autoUpgrade", "upgradedFromVersionId", "enabled", "config", "hosts", "createdAt", "updatedAt", "version", "requiredSecrets", "missingSecrets", "storedSecrets", "updateAvailable", "webhookUrl", "pendingChange", "aliases", "upgrade", "circuit" ], "additionalProperties": false } } }, "required": ["name", "publisher", "latest", "versions", "installs"], "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false } }, "signatures": { "type": "string", "enum": ["off", "optional", "required"] } }, "required": ["entry", "versions", "signatures"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions": { "get": { "summary": "The versions of an app the tenant sees, the highest number first", "tags": ["apps"], "description": "The platform's published versions (and the withdrawn ones the tenant's installs still run on, or may move back to after an automatic upgrade) and the tenant's own uploads whatever their status, each with its manifest unfolded, ordered by version number (SemVer precedence: `1.10.0` above `1.9.0`, a release above its prereleases). `platformSource` says whether a platform version comes from a release or from the operator. `review` is the operator's latest review of one of the tenant's own versions: `pending` while it waits for the operator, `rejected` with the operator's `comment`; `null` when it was never reviewed. `provenance` says who signed the module and from what source, and whether the operator's policy trusts that signer as it is now (`trusted`, `trustedSigner`); `null` for an unsigned version.", "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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 or published; its module stays in storage. Its open publish request and the operator's review it waits for are closed as `withdrawn`. Audited as `app.withdrawn`, with the request and the review it closed. 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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/approve": { "post": { "summary": "Approve an open publish request and publish the version", "tags": ["apps"], "description": "Publishes the version (200), or, when the tenant's versions wait for the operator's review (`appReview` `required`), opens that review instead (202 with the pending `review`): the version stays `uploaded` until the operator decides. With four-eyes on (`approvals.fourEyes`), never by its requester: 403 `four_eyes`. 404 without an open request, 409 `conflict` for a version no longer uploaded or waiting for the operator's review already, 409 `app_blocked` for a module the operator blocked, and 409 `provenance_required` when the deployment requires provenance and no signer the operator's policy trusts now has signed it (the request stays open either way; the provenance is weighed again as the version publishes, so a bundle attached after the decision is refused too, the request then decided and the version still `uploaded`). Audited as `app.approval.decided`, and `app.review.requested` when a review is opened.", "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval", "review"], "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval", "review"], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/provenance": { "put": { "summary": "Attach a Sigstore bundle to an uploaded version: who signed its module, from what source", "tags": ["apps"], "description": "The body is a Sigstore bundle (JSON, v0.1 to v0.3, 64 KiB at most: 413 `payload_too_large` beyond), as cosign v3 (`sign-blob --bundle`) and GitHub's artifact attestations (`gh attestation download`) write one: a message signature over the module, or an in-toto attestation naming the module's SHA-256 as a subject. It must sign the module as stored: an SDK build (`dist/app.wasm`) carries its memory maximum and is stored as built. A keyless signature is verified against the deployment's Sigstore trusted roots, one made with a key against the keys the operator pins. What it proves (the signer, the source a certificate or an attestation names, the transparency log entry, when it was signed) replaces what the version carried. `provenance.trusted` and `trustedSigner` say whether the operator's policy trusts the signer: a signature it does not trust is recorded all the same, and trust is computed again wherever the version is shown, so a signer the operator stops trusting is trusted nowhere. When the deployment requires provenance, the tenant's versions publish, install and upgrade only with a signer it trusts (409 `provenance_required` otherwise). One of the tenant's own versions while it is `uploaded`: 409 `provenance_locked` with `details.reason` (`published`, `withdrawn`, `approval`, `review`) once it is published or withdrawn and while a publish request or the operator's review of it is open. 400 `provenance_invalid` with `details.reason`: `malformed`, `unsupported`, `digest_mismatch` (it signs other bytes than the module) or `signature`. 503 `provenance_unavailable` while a trusted root cannot be loaded. 404 `signatures_off` when the deployment takes no provenance, 404 for a platform version or another tenant's. Audited as `app.provenance.recorded`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "A Sigstore bundle (`application/vnd.dev.sigstore.bundle.v0.3+json`, or v0.1 and v0.2), as `cosign sign-blob --bundle` and `gh attestation download` write it." } } }, "description": "A Sigstore bundle (`application/vnd.dev.sigstore.bundle.v0.3+json`, or v0.1 and v0.2), as `cosign sign-blob --bundle` and `gh attestation download` write it." }, "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "additionalProperties": false } } } } } } }, "/apps/{name}/versions/{id}/publish": { "post": { "summary": "Publish an uploaded version, or request its approval or the operator's review", "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, when the tenant's versions wait for the operator's review (`appReview` `required` on `GET /tenants/me`), the operator's review is opened (202 with the pending `review`): the version stays `uploaded` until the operator approves it, which publishes it, or rejects it with a comment, after which it can be published again. Otherwise the version is published at once (200, `approval` and `review` null). Audited as `app.approval.requested`, `app.review.requested` or `app.published`. 404 for a platform version or another tenant's, 409 `conflict` for a version already published or withdrawn or waiting for the operator's review, 409 `app_blocked` for a module the operator blocked. When the deployment requires provenance (`APP_SIGNATURES` `required`), 409 `provenance_required` (`details.reason` `unsigned` or `untrusted`) for a version no signer the operator's policy trusts now has signed, before any request or review opens: attach a bundle with `PUT /apps/:name/versions/:id/provenance`.", "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval", "review"], "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval", "review"], "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"] }, "platformSource": { "anyOf": [ { "type": "string", "enum": ["release", "operator"] }, { "type": "null" } ] }, "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 }, "title": { "type": "string" }, "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", "maxLength": 200 }, "requiredWhen": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "in": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": ["config"], "additionalProperties": false } } }, "required": ["name"], "additionalProperties": false } }, "hosts": { "type": "array", "items": { "type": "string", "maxLength": 259, "pattern": "^((\\*\\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\\.)+[a-z][a-z0-9-]*|localhost|(\\d{1,3}\\.){3}\\d{1,3})(:[1-9]\\d{0,4})?$" } }, "hostsFromConfig": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "secretsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "needs": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "documentsFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "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": "^(\\/([^/~\\p{Cc}]|~[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 } ] }, "webhookExternalIdFromConfig": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "handoff": { "type": "boolean" } }, "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 }, "mappable": { "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "inputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputSchema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "outputFromInput": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["schema"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" } }, "required": ["kind", "output", "input"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["keys"] }, "output": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "input": { "type": "string", "maxLength": 200, "pattern": "^(\\/([^/~\\p{Cc}]|~[01])*)+$" }, "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" } }, "required": ["kind", "output", "input", "key"], "additionalProperties": false } ] } } }, "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" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] }, "provenance": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["signature", "attestation", "release"] }, "signer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["keyless"] }, "identity": { "type": "string", "minLength": 1 }, "issuer": { "type": "string", "minLength": 1 } }, "required": ["type", "identity", "issuer"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["key"] }, "hint": { "type": ["string", "null"] }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": ["type", "hint", "fingerprint"], "additionalProperties": false } ] }, { "type": "null" } ] }, "source": { "type": "object", "properties": { "repository": { "type": ["string", "null"] }, "ref": { "type": ["string", "null"] }, "commit": { "type": ["string", "null"] } }, "required": ["repository", "ref", "commit"], "additionalProperties": false }, "transparencyLogIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "format": "date-time" }, "recordedBy": { "type": "string" }, "trusted": { "type": "boolean" }, "trustedSigner": { "type": ["string", "null"] } }, "required": [ "kind", "signer", "source", "transparencyLogIndex", "signedAt", "verifiedAt", "recordedBy", "trusted", "trustedSigner" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "publisher", "platformSource", "name", "version", "status", "sha256", "sizeBytes", "capabilities", "secrets", "hosts", "hostsFromConfig", "needs", "memoryMiB", "handles", "actions", "configSchema", "createdAt", "publishedAt", "review", "provenance" ], "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", "withdrawn"] }, { "type": "null" } ] }, "decisionComment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "requestedBy", "requestedAt", "comment", "decidedBy", "decidedAt", "decision", "decisionComment" ], "additionalProperties": false }, { "type": "null" } ] }, "review": { "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})$" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected", "withdrawn"] }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time" }, "decidedBy": { "type": ["string", "null"] }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "comment": { "type": ["string", "null"] } }, "required": [ "id", "tenantId", "versionId", "status", "requestedBy", "requestedAt", "decidedBy", "decidedAt", "comment" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["version", "approval", "review"], "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", "operator"] }, "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", "operator" ] }, "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", "operator"] }, "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", "operator"] }, "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", "operator"] }, "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", "operator" ] }, "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", "operator" ] }, "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", "operator" ] }, "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", "operator" ] }, "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", "operator" ] }, "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", "operator" ] }, "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", "operator" ] }, "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})$" }, "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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 }, "reusedConnections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ai": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["requests", "inputTokens", "outputTokens"], "additionalProperties": false } }, "required": ["httpRequests", "documentReads", "logLines"], "additionalProperties": false }, { "type": "null" } ] }, "fallbackOf": { "anyOf": [ { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "required": ["installId", "installName"], "additionalProperties": false }, { "type": "null" } ] }, "resultLabel": { "type": "string" } }, "required": [ "id", "tenantId", "installId", "installName", "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": "The vendor's page where the applicant continues the check their run waits for", "tags": ["collection-submissions"], "description": "Applicants only. After the submit the run may wait for a vendor session the applicant takes part in (a liveness check, documents the vendor collects itself), started by an install whose version declares `handles.handoff`; `GET …/status` says `handoff: true` while one waits. The newest such session's module (the version that started it, run with the install's config, the secrets it requires, its approved hosts and its cached values, which keep what it changes of them) answers the vendor's hosted page for it: `handoff: { url, expiresAt }`. Send the applicant there, and ask again for a link that expired. The vendor sends them back to their page of the submission in the terminal (the tenant's `collection.flowUrl`, else the deployment's, then `/flow/{id}`, without a token). `handoff: null` when the vendor needs nothing more from the applicant and the run waits for its webhook. 409 `handoff_unavailable` when nothing waits for the applicant: the submission is not sent, or its run waits for no such session through an enabled install on a module the operator has not blocked. 502 `handoff_failed` when the runner or the module fails, a secret the install requires has no value, or the page is not https on one of the install's approved hosts and ports. Audited as `collection.submission.handoff_started` with the page's host (and its port when not the default), never its URL. Every hand-off the install's module runs counts as a hand-off of the install (`GET /apps/metering`), apart from its calls: no quota or budget refuses 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": { "handoff": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "maxLength": 4000, "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["url", "expiresAt"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["handoff"], "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 session the applicant takes part in, started by an install whose version declares `handles.handoff`: `GET …/handoff` answers the vendor's page for it.", "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. The pack's `installs` declare each install the exported definitions call, by the name they call it, with the app the tenant's install runs; a definition calling an install the tenant does not have is a 409 `unknown_install` (`details.installs` lists each with the items calling it). Installs themselves, their configuration and secrets 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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": [ "app", "action", "input", "inputMapping" ], "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 }, "installs": { "default": {}, "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "additionalProperties": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } } }, "required": ["name", "version", "definitions", "installs"], "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. The pack's `installs` are weighed against the tenant's: an install of that name (or a former name an install keeps) running another app is an item of kind `install`. The answer lists each declared install: `present`, or `missing` with `appAvailable` (the catalogue offers the app, so an install of that name can be created); with `issues` for the actions the present install cannot answer (`unknown_action`, or `async_action` for an `app` rule), which refuse the pack as `install` items only with `publish=true`. 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. A missing install does not stop a publish.", "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 } } }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action"] } }, "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"] } } } }, "installs": { "default": {}, "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "additionalProperties": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } } }, "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 } }, "installs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "app": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "status": { "type": "string", "enum": ["present", "missing"] }, "actions": { "type": "array", "items": { "type": "string" } }, "appAvailable": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unknown_action", "async_action"] }, "action": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "action", "message"], "additionalProperties": false } } }, "required": ["name", "app", "status", "actions", "appAvailable", "issues"], "additionalProperties": false } } }, "required": [ "name", "version", "publish", "approvalRequired", "definitions", "lists", "installs" ], "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 } }, "installs": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "additionalProperties": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } } }, "required": ["id", "name", "version", "description", "counts", "installs"], "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 installs 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 install failed a call in the last hour or has an open circuit, `ok` otherwise, with the failing installs (each with the catalogue app it runs) 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": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" }, "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": [ "installId", "installName", "appName", "calls", "failures", "timeouts", "p95Ms", "lastInvokedAt", "lastErrorAt" ], "additionalProperties": false } }, "circuits": { "type": "array", "items": { "type": "object", "properties": { "installId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, "installName": { "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 }, "failureThreshold": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "installId", "installName", "state", "since", "failures", "failureThreshold" ], "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` (the circuit of an install opened; `apps:write`), `app_blocked` (the operator blocked the module an install runs, with the reason; `apps:write`), `app_review_decided` (the operator approved or rejected one of the tenant's app versions; `apps:publish`) 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", "app_blocked", "app_review_decided", "app_upgraded", "app_quota_exceeded", "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, a fallback naming the rule's own install included), `unknown_list` (a list lookup names a list that does not exist), `unknown_install` (an app rule names an install the tenant does not have), `unknown_action` (the version the install runs has no such action), `async_action` (the action answers through a webhook), `unmappable_input` (`inputMapping` sets a field the action takes no run data in: its `mappable` names the others). An app rule's `fallback` is weighed as the rule's own call, its issues under `config.fallback`. 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), `install_renamed` (the install is named by a former name it keeps as an alias), `install_disabled`, `install_pending` (a new install waiting for its first approval), `rule_disabled`, `unknown_result_path` (the result path reads no field the action's output declares), `rule_action_timeout` (the action may run longer than 50 s, most of the minute a step's rules share).", "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" } }, "pickers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "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 install is 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. The worker keeps the events `RETENTION_SUBMISSION_EVENT_DAYS` (90 by default, never fewer than the 90-day window). 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`), saves of installs waiting for an approval with the oldest three (`install_change_pending`; `apps:publish`), installs that are disabled or miss a secret their config requires (`apps:write`; a new install waiting for its first approval counts as its change only), installs that upgrade automatically whose move waits for a secret, a config fix or definitions calling an action the target lacks (`install_upgrade_waiting`, `apps:write`; a move waiting for an approval shows as its change), installs 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": ["install_change_pending"] }, "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})$" }, "install": { "type": "string" }, "origin": { "type": "string", "enum": ["save", "auto_upgrade"] }, "hostsAdded": { "type": "array", "items": { "type": "string" } }, "needsAdded": { "type": "array", "items": { "type": "string", "enum": ["documents"] } }, "handlesAdded": { "type": "array", "items": { "type": "string", "enum": ["webhook", "handoff"] } } }, "required": [ "id", "install", "origin", "hostsAdded", "needsAdded", "handlesAdded" ], "additionalProperties": false } } }, "required": ["kind", "count", "oldest"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["install_upgrade_waiting"] }, "install": { "type": "string" }, "target": { "type": "string" }, "waitingFor": { "type": "string", "enum": ["approval", "secrets", "config", "actions", "declined"] } }, "required": ["kind", "install", "target", "waitingFor"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["install_disabled"] }, "install": { "type": "string" } }, "required": ["kind", "install"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["install_unconfigured"] }, "install": { "type": "string" }, "missingSecrets": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": ["kind", "install", "missingSecrets"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": ["install_failing"] }, "install": { "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", "install", "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", "operator" ] }, "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`). `retention` is how long the deployment keeps what its worker deletes, in days, the same for every tenant (`RETENTION_APP_CALLBACK_DAYS`, `RETENTION_SUBMISSION_EVENT_DAYS`; `null` keeps it forever). `appReview` is `required` when the tenant's own app versions wait for the operator's review before they publish: the operator sets it (`pnpm ops`), and a new tenant starts with the deployment's `APP_REVIEW_DEFAULT`.", "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" } ] }, "appReview": { "type": "string", "enum": ["off", "required"] }, "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 }, "retention": { "type": "object", "properties": { "appCallbackDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "submissionEventDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["appCallbackDays", "submissionEventDays"], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "appReview", "console", "counts", "retention" ], "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" } ] }, "appReview": { "type": "string", "enum": ["off", "required"] }, "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 }, "retention": { "type": "object", "properties": { "appCallbackDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "submissionEventDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["appCallbackDays", "submissionEventDays"], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "appReview", "console", "counts", "retention" ], "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" } ] }, "appReview": { "type": "string", "enum": ["off", "required"] }, "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 }, "retention": { "type": "object", "properties": { "appCallbackDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "submissionEventDays": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["appCallbackDays", "submissionEventDays"], "additionalProperties": false } }, "required": [ "id", "name", "idpOrgId", "provisionedAt", "region", "status", "suspendedAt", "suspendedReason", "linksValidAfter", "appReview", "console", "counts", "retention" ], "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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` with the URL's origin, its path and query masked (`https://hooks.example.com/••••?••••`): either can hold the receiver's token. 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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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 and the URL masked as on creation.", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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 masked as on creation (the origin only, the path and query hidden).", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "submission.link_requested" ] }, "description": { "type": "string" }, "resourceType": { "type": "string" }, "samplePayload": {} }, "required": ["name", "description", "resourceType", "samplePayload"], "additionalProperties": false } } }, "required": ["items"], "additionalProperties": false } } } } } } }, "/webhooks/app-installs/{installId}": { "post": { "summary": "Vendor webhook for an install's asynchronous calls (checked by its app)", "tags": ["webhooks"], "description": "Each install has its own URL, the `webhookUrl` of its view and the `callbackUrl` its module hands the vendor: a webhook only reaches the sessions of that install. 404 `unknown_install` when no install has the id (a removed install's URL included). The external id is `?externalId=` when present, else read where the installed version declares it (`handles.webhookExternalId`: a JSON Pointer into a JSON body, a header or a query parameter) or, for a version that leaves the source to each install (`handles.webhookExternalIdFromConfig`), where the install's config says: text of 1 to 200 characters, or an integer read as its decimal text; 400 `missing_external_id` without one (an install whose config sets no source receives no webhooks, and its `webhookUrl` is `null`). 404 `not_found` when no session of the install has the id; 409 `app_blocked` when the operator blocked the module of the version that started the session, without the block's reason or the module's hash, since the request is not checked yet (the session waits on until its timeout); 401 `webhook_rejected` when the app refuses the signature or payload, or answers an event that names another session than the one the request found (so for an app that reads the id from what its vendor signed, as an `http-api` install does under every scheme but `token`, a query or a header that points a signed body at another session completes none; an app that reads it from the query or an unsigned header, as an `http-api` install's webhook settings may say only under `token`, which signs nothing, answers the value read here, which a replayed request can point at another pending session); 409 `install_not_configured` while a secret the install's config requires has no stored value (the app gets only those secrets); 502 `app_webhook_failed` when the app or the runner fails. 202 `{ ignored: true }` for a request the app drops, 200 `{ duplicate: true }` for an event id the install already received (an app whose vendor signs no event id answers a digest of the external id and the body, so a re-delivery counts once and the same body sent for two sessions counts for each), 200 `{ stale: true }` for a session already settled (a delivery that settles it at the same moment included), 202 `{ accepted: true }` for an event that keeps the session pending; otherwise the session completes, the run waiting on it is told (only by the delivery that completed it) and the answer names it with its `status`. The module handles it with the install's config, the secrets it requires, its approved hosts and its live cached values, and what it changes of those values is kept, whatever it answers. Every request the install's module handles counts as a webhook handling of the install (`GET /apps/metering`), apart from its calls: no quota or budget refuses a webhook.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "externalId", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "installId", "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 version the named install runs). `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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 } } }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action"] } }, "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 } } }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action"] } }, "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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 }, "fallback": { "type": "object", "properties": { "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" } } }, "required": ["app", "action", "input", "inputMapping"], "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), its forms still in progress, its own and the follow-ups of requests for information, are withdrawn, and its app sessions still waiting for a vendor's webhook fail with error `run_cancelled`, so they no longer hold their install. Writes `workflow.run.cancelled` with the reason and what was closed (`closedCaseIds`, `withdrawnSubmissionIds`, `failedCallbackIds`), plus a `case.closed` or `collection.submission.withdrawn` event for each case and form. 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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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", "app.install.change.requested", "app.install.upgraded", "app.module.blocked", "app.quota.exceeded", "app.review.decided", "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": [] } ] }