{ "openapi": "3.1.0", "info": { "title": "Stateway API", "description": "Motor de Processos BPMN 2.0 como BaaS", "version": "0.1.0" }, "components": { "schemas": {} }, "paths": { "/health": { "get": { "tags": [ "Health" ], "description": "Liveness probe", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "version": { "type": "string" } } } } } } }, "operationId": "listHealth", "summary": "Liveness probe" } }, "/health/ready": { "get": { "tags": [ "Health" ], "description": "Readiness probe (checks DB connection)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "database": { "type": "string" }, "redis": { "type": "string" }, "search": { "type": "object", "properties": { "trigramEnabled": { "type": "boolean" }, "unaccentEnabled": { "type": "boolean" } } }, "timestamp": { "type": "string" } } } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "database": { "type": "string" }, "redis": { "type": "string" }, "timestamp": { "type": "string" } } } } } } }, "operationId": "listHealthReady", "summary": "Readiness probe (checks DB connection)" } }, "/v1/tenant": { "get": { "tags": [ "Tenant" ], "description": "Get current tenant data", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" }, "settings": { "type": "object" }, "createdAt": { "type": "string" } } } } } } } } }, "operationId": "listV1Tenant", "summary": "Get current tenant data" }, "put": { "tags": [ "Tenant" ], "description": "Update tenant settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "settings": { "type": "object" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } } }, "operationId": "putV1Tenant", "summary": "Update tenant settings" } }, "/v1/register": { "post": { "tags": [ "Auth" ], "description": "Register a new tenant. Sends a 6-digit verification code to the provided email.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "operationId": "postV1Register", "summary": "Register a new tenant. Sends a 6-digit verification code to the provided email." } }, "/v1/register/verify": { "post": { "tags": [ "Auth" ], "description": "Verify the email code and activate the tenant. Returns the first API key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenantId", "verificationCode" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "verificationCode": { "type": "string", "minLength": 6, "maxLength": 6 } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string" } } }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } } } } } } } } } } }, "operationId": "postV1RegisterVerify", "summary": "Verify the email code and activate the tenant. Returns the first API key." } }, "/v1/auth/keys": { "post": { "tags": [ "Auth" ], "description": "Create a new API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [] }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } } } } } } } } }, "operationId": "postV1AuthKeys", "summary": "Create a new API key" }, "get": { "tags": [ "Auth" ], "description": "List API keys for current tenant", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "revokedAt": { "type": "string" } } } } } } } } } }, "operationId": "listV1AuthKeys", "summary": "List API keys for current tenant" } }, "/v1/auth/keys/{id}": { "delete": { "tags": [ "Auth" ], "description": "Revoke an API key", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revokedAt": { "type": "string" } } } } } } } } }, "operationId": "deleteV1AuthKeys_id_", "summary": "Revoke an API key" } }, "/v1/definitions": { "post": { "tags": [ "Definitions" ], "description": "Create a new process definition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "source_type", "source" ], "properties": { "key": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "source_type": { "type": "string", "enum": [ "bpmn", "bpmn-base64", "json", "yaml" ] }, "source": {} } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } }, "operationId": "postV1Definitions", "summary": "Create a new process definition" }, "get": { "tags": [ "Definitions" ], "description": "List process definitions", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string", "description": "SHA-256 hash of the definition source content" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } } }, "operationId": "listV1Definitions", "summary": "List process definitions" } }, "/v1/definitions/{key}": { "get": { "tags": [ "Definitions" ], "description": "Get latest active version of a process definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string", "description": "SHA-256 hash of the definition source content" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } }, "operationId": "listV1Definitions_key_", "summary": "Get latest active version of a process definition" }, "put": { "tags": [ "Definitions" ], "description": "Create a new version of a process definition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_type", "source" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "source_type": { "type": "string", "enum": [ "bpmn", "bpmn-base64", "json", "yaml" ] }, "source": {} } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "putV1Definitions_key_", "summary": "Create a new version of a process definition" }, "delete": { "tags": [ "Definitions" ], "description": "Delete a process definition (soft-delete)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Definitions_key_", "summary": "Delete a process definition (soft-delete)" } }, "/v1/definitions/{key}/versions": { "get": { "tags": [ "Definitions" ], "description": "List all versions of a process definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string", "description": "SHA-256 hash of the definition source content" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } } }, "operationId": "listV1Definitions_key_Versions", "summary": "List all versions of a process definition" } }, "/v1/definitions/{key}/versions/{v}": { "get": { "tags": [ "Definitions" ], "description": "Get a specific version of a process definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "v", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string", "description": "SHA-256 hash of the definition source content" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } }, "operationId": "listV1Definitions_key_Versions_v_", "summary": "Get a specific version of a process definition" } }, "/v1/definitions/{key}/versions/{v}/verify": { "get": { "tags": [ "Definitions" ], "description": "Get hash verification info for a specific definition version", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "v", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "version": { "type": "number" }, "source_hash": { "type": "string", "description": "SHA-256 hash of the stored definition source" }, "algorithm": { "type": "string", "description": "Hash algorithm used (always sha256)" }, "how_to_verify": { "type": "string", "description": "Instructions to verify the source file locally" } } } } } } } } }, "operationId": "listV1Definitions_key_Versions_v_Verify", "summary": "Get hash verification info for a specific definition version" } }, "/v1/definitions/{key}/rollback": { "post": { "tags": [ "Definitions" ], "description": "Rollback a process definition to a previous version", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1 } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Definitions_key_Rollback", "summary": "Rollback a process definition to a previous version" } }, "/v1/definitions/{key}/xml": { "get": { "tags": [ "Definitions" ], "description": "Export process definition as BPMN XML", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "layout", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "annotations", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "annotationTypes", "required": false }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "version", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Definitions_key_Xml", "summary": "Export process definition as BPMN XML" } }, "/v1/definitions/{key}/preview.mermaid": { "get": { "tags": [ "Definitions" ], "description": "Generate a Mermaid flowchart diagram from a process definition", "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "version", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Definitions_key_Preview.mermaid", "summary": "Generate a Mermaid flowchart diagram from a process definition" } }, "/v1/instances": { "post": { "tags": [ "Instances" ], "description": "Start a new process instance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "definition_key" ], "properties": { "definition_key": { "type": "string" }, "definition_version": { "type": "number" }, "correlation_id": { "type": "string" }, "variables": { "type": "object", "default": {} }, "metadata": { "type": "object", "default": {} }, "source_instance_id": { "type": "string", "format": "uuid", "description": "Re-run a partir de instância existente" } } } } } }, "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances", "summary": "Start a new process instance" }, "get": { "tags": [ "Instances" ], "description": "List process instances", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "definition_hash": { "type": "string", "description": "SHA-256 hash of the definition source at instantiation time" }, "correlation_id": { "type": "string" }, "started_at": { "type": "string" }, "ended_at": { "type": "string" } } } } } } } } } }, "operationId": "listV1Instances", "summary": "List process instances" } }, "/v1/instances/{id}": { "get": { "tags": [ "Instances" ], "description": "Get process instance details", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "definition_hash": { "type": "string", "description": "SHA-256 hash of the definition source at instantiation time" }, "correlation_id": { "type": "string" }, "variables": { "type": "object", "additionalProperties": true }, "started_at": { "type": "string" }, "ended_at": { "type": "string" } } } } } } } } }, "operationId": "listV1Instances_id_", "summary": "Get process instance details" } }, "/v1/instances/{id}/verify": { "get": { "tags": [ "Instances" ], "description": "Verify if the definition hash stored at instantiation matches the current definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "instance_id": { "type": "string" }, "definition_key": { "type": "string" }, "definition_version": { "type": "number" }, "definition_hash": { "type": "string", "description": "SHA-256 hash stored at instantiation time" }, "current_definition_hash": { "type": "string", "description": "Current SHA-256 hash of the definition" }, "hash_match": { "type": "boolean", "description": "true if the definition has not changed since instantiation" }, "algorithm": { "type": "string" } } } } } } } } }, "operationId": "listV1Instances_id_Verify", "summary": "Verify if the definition hash stored at instantiation matches the current definition" } }, "/v1/instances/{id}/tokens": { "get": { "tags": [ "Instances" ], "description": "Get execution tokens", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Instances_id_Tokens", "summary": "Get execution tokens" }, "post": { "tags": [ "Instances" ], "description": "Add a new token to a specific element", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "element_id" ], "properties": { "element_id": { "type": "string", "description": "Element ID to place the new token at" }, "variables": { "type": "object", "description": "Variables to merge before adding" }, "reason": { "type": "string", "description": "Audit reason" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "new_token_id": { "type": "string" }, "element_id": { "type": "string" }, "element_type": { "type": "string" } } } } } } } } }, "operationId": "postV1Instances_id_Tokens", "summary": "Add a new token to a specific element" } }, "/v1/instances/{id}/tokens/{tokenId}/retry": { "post": { "tags": [ "Instances" ], "description": "Retry a failed token (manual incident resolution)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "description": "Variables to merge before retry" }, "reason": { "type": "string", "description": "Audit reason" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "new_token_id": { "type": "string" }, "original_token_id": { "type": "string" }, "element_id": { "type": "string" }, "element_type": { "type": "string" }, "instance_status": { "type": "string" }, "variables_patched": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "operationId": "postV1Instances_id_Tokens_tokenId_Retry", "summary": "Retry a failed token (manual incident resolution)" } }, "/v1/instances/{id}/suspend": { "post": { "tags": [ "Instances" ], "description": "Suspend process instance", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances_id_Suspend", "summary": "Suspend process instance" } }, "/v1/instances/{id}/resume": { "post": { "tags": [ "Instances" ], "description": "Resume suspended instance", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances_id_Resume", "summary": "Resume suspended instance" } }, "/v1/instances/{id}/terminate": { "post": { "tags": [ "Instances" ], "description": "Terminate process instance", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances_id_Terminate", "summary": "Terminate process instance" } }, "/v1/instances/{id}/variables": { "get": { "tags": [ "Instances" ], "description": "Get instance variables", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_download_url", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Instances_id_Variables", "summary": "Get instance variables" }, "post": { "tags": [ "Instances" ], "description": "Update instance variables", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances_id_Variables", "summary": "Update instance variables" } }, "/v1/instances/{id}/tokens/{tokenId}/move": { "post": { "tags": [ "Instances" ], "description": "Move a token to another element (token repositioning)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_element_id" ], "properties": { "target_element_id": { "type": "string", "description": "Target element ID in the process definition" }, "variables": { "type": "object", "description": "Variables to merge before moving" }, "reason": { "type": "string", "description": "Audit reason" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "new_token_id": { "type": "string" }, "original_token_id": { "type": "string" }, "from_element_id": { "type": "string" }, "to_element_id": { "type": "string" }, "instance_status": { "type": "string" } } } } } } } } }, "operationId": "postV1Instances_id_Tokens_tokenId_Move", "summary": "Move a token to another element (token repositioning)" } }, "/v1/instances/{id}/tokens/{tokenId}": { "delete": { "tags": [ "Instances" ], "description": "Cancel an active token (manual token cancellation)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Audit reason" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled_token_id": { "type": "string" }, "element_id": { "type": "string" }, "remaining_active_tokens": { "type": "number" } } } } } } } } }, "operationId": "deleteV1Instances_id_Tokens_tokenId_", "summary": "Cancel an active token (manual token cancellation)" } }, "/v1/instances/terminate-bulk": { "post": { "tags": [ "Instances" ], "description": "Terminate all running instances of a definition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "definition_key" ], "properties": { "definition_key": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "terminated": { "type": "number" }, "instanceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } }, "operationId": "postV1InstancesTerminate-bulk", "summary": "Terminate all running instances of a definition" } }, "/v1/instances/{id}/history": { "get": { "tags": [ "Instances" ], "description": "Get audit history for a process instance. Includes engine events (gateway.resolved, element.entered, etc.), API-level events, and DataStore resolution events.", "parameters": [ { "schema": { "type": "string", "enum": [ "api_key", "system", "timer", "engine" ] }, "in": "query", "name": "actor_type", "required": false, "description": "Filter by actor type" }, { "schema": { "type": "string" }, "in": "query", "name": "action", "required": false, "description": "Filter by action name (e.g. gateway.resolved)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Start of time range (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "End of time range (ISO 8601)" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "page_size", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "actorType": { "type": "string" }, "action": { "type": "string" }, "payload": {}, "createdAt": { "type": "string" } } } } } } } } } }, "operationId": "listV1Instances_id_History", "summary": "Get audit history for a process instance. Includes engine events (gateway.resolved, element.entered, etc.), API-level events, and DataStore resolution events." } }, "/v1/instances/{id}/files": { "post": { "tags": [ "Files" ], "description": "Request an upload slot for a file variable. Returns a pre-signed URL the client uploads to directly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "variable_name", "filename", "mime_type", "size_bytes" ], "properties": { "variable_name": { "type": "string", "description": "Name of the instance variable that will hold the file_ref once confirmed." }, "filename": { "type": "string", "description": "Original filename (max 255 chars); must not contain slashes, backslashes or control characters." }, "mime_type": { "type": "string", "description": "Concrete MIME type (e.g. 'application/pdf'); wildcards such as 'application/*' are rejected." }, "size_bytes": { "type": "integer", "description": "Declared file size in bytes; must be positive and not exceed MAX_FILE_SIZE_BYTES." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-Stateway-Storage-Used": { "schema": { "type": "string" }, "description": "Total bytes currently used by the tenant in storage, after this operation." }, "X-Stateway-Storage-Quota": { "schema": { "type": "string" }, "description": "Total storage quota (bytes) allotted to the tenant." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ref_id": { "type": "string", "description": "Identifier of the pending file reference." }, "upload_url": { "type": "string", "description": "Pre-signed URL the client uploads the file to directly." }, "expires_at": { "type": "string", "description": "When the upload URL stops accepting the PUT (FILE_UPLOAD_URL_TTL_SECONDS)." }, "method": { "type": "string", "description": "HTTP method the client must use against upload_url." }, "headers": { "type": "object", "additionalProperties": true, "description": "Headers the client must send on the PUT request." } } } } } } } }, "400": { "description": "Validation failed: malformed body, size_bytes exceeds MAX_FILE_SIZE_BYTES, or mime_type is a wildcard.", "content": { "application/json": { "schema": { "type": "object", "description": "Validation failed: malformed body, size_bytes exceeds MAX_FILE_SIZE_BYTES, or mime_type is a wildcard.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "402": { "description": "Storage quota exceeded for the tenant.", "content": { "application/json": { "schema": { "type": "object", "description": "Storage quota exceeded for the tenant.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "STORAGE_QUOTA_EXCEEDED" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Instance or tenant not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Instance or tenant not found.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Instance is not accepting file uploads in its current status (only running or suspended instances do).", "content": { "application/json": { "schema": { "type": "object", "description": "Instance is not accepting file uploads in its current status (only running or suspended instances do).", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "The target variable is declared with a type that is not a stateway:file scalar.", "content": { "application/json": { "schema": { "type": "object", "description": "The target variable is declared with a type that is not a stateway:file scalar.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VARIABLE_TYPE_MISMATCH" ] }, "message": { "type": "string" }, "details": {} } } } } } } } }, "operationId": "postV1Instances_id_Files", "summary": "Request an upload slot for a file variable. Returns a pre-signed URL the client uploads to directly." } }, "/v1/instances/{id}/files/{ref_id}/confirm": { "post": { "tags": [ "Files" ], "description": "Confirm that the upload completed. Verifies the object in storage and populates the instance variable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Optional free-form business metadata merged into the file_ref value once confirmed." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "ref_id", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-Stateway-Storage-Used": { "schema": { "type": "string" }, "description": "Total bytes currently used by the tenant in storage, after this operation." }, "X-Stateway-Storage-Quota": { "schema": { "type": "string" }, "description": "Total storage quota (bytes) allotted to the tenant." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "variable_name": { "type": "string", "description": "Instance variable that now holds the confirmed file_ref." }, "file_ref": { "type": "object", "additionalProperties": true, "description": "The confirmed file_ref value (object_key/bucket omitted; PRD §3.2/§5.1)." } } } } } } } }, "400": { "description": "Validation failed: request body does not match the expected shape, or confirming would push the instance variables payload past MAX_VARIABLES_PAYLOAD_BYTES.", "content": { "application/json": { "schema": { "type": "object", "description": "Validation failed: request body does not match the expected shape, or confirming would push the instance variables payload past MAX_VARIABLES_PAYLOAD_BYTES.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "402": { "description": "Storage quota exceeded; the tenant quota was exhausted between slot creation and confirmation.", "content": { "application/json": { "schema": { "type": "object", "description": "Storage quota exceeded; the tenant quota was exhausted between slot creation and confirmation.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "STORAGE_QUOTA_EXCEEDED" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "File reference or instance not found.", "content": { "application/json": { "schema": { "type": "object", "description": "File reference or instance not found.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Upload already confirmed (retry of a completed confirmation, or a concurrent request won the race).", "content": { "application/json": { "schema": { "type": "object", "description": "Upload already confirmed (retry of a completed confirmation, or a concurrent request won the race).", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "410": { "description": "The upload slot expired, or the file reference was already deleted.", "content": { "application/json": { "schema": { "type": "object", "description": "The upload slot expired, or the file reference was already deleted.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FILE_REF_DELETED", "UPLOAD_EXPIRED" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "The uploaded object was not found in storage, or its measured size does not match the declared size_bytes beyond a 1-byte tolerance.", "content": { "application/json": { "schema": { "type": "object", "description": "The uploaded object was not found in storage, or its measured size does not match the declared size_bytes beyond a 1-byte tolerance.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PROCESS_ERROR" ] }, "message": { "type": "string" }, "details": {} } } } } } } } }, "operationId": "postV1Instances_id_Files_ref_id_Confirm", "summary": "Confirm that the upload completed. Verifies the object in storage and populates the instance variable." } }, "/v1/instances/{id}/variables/{var_name}/download": { "get": { "tags": [ "Files" ], "description": "Redirects (302) to a pre-signed GET URL for the file_ref variable, valid for FILE_DOWNLOAD_URL_TTL_SECONDS (default 5 min). Sets X-Stateway-File-Ref, X-Stateway-Filename (percent-encoded UTF-8) and X-Stateway-Mime-Type headers.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "var_name", "required": true } ], "responses": { "302": { "description": "Redirect to a pre-signed download URL for the file.", "headers": { "Location": { "schema": { "type": "string" }, "description": "Pre-signed GET URL, valid for FILE_DOWNLOAD_URL_TTL_SECONDS." }, "X-Stateway-File-Ref": { "schema": { "type": "string" }, "description": "Identifier of the resolved file reference." }, "X-Stateway-Filename": { "schema": { "type": "string" }, "description": "Original filename, percent-encoded UTF-8 (RFC 3986)." }, "X-Stateway-Mime-Type": { "schema": { "type": "string" }, "description": "MIME type of the file." } } }, "404": { "description": "Instance, variable, or file reference not found; or the variable is not a file variable.", "content": { "application/json": { "schema": { "type": "object", "description": "Instance, variable, or file reference not found; or the variable is not a file variable.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "410": { "description": "The file was deleted. details carries the tombstone (or just ref_id when the variable itself is stale).", "content": { "application/json": { "schema": { "type": "object", "description": "The file was deleted. details carries the tombstone (or just ref_id when the variable itself is stale).", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FILE_REF_DELETED" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "The variable resolves to a file reference whose upload has not been confirmed yet.", "content": { "application/json": { "schema": { "type": "object", "description": "The variable resolves to a file reference whose upload has not been confirmed yet.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FILE_REF_PENDING" ] }, "message": { "type": "string" }, "details": {} } } } } } } } }, "operationId": "listV1Instances_id_Variables_var_name_Download", "summary": "Redirects (302) to a pre-signed GET URL for the file_ref variable, valid for FILE_DOWNLOAD_URL_TTL_SECONDS (default 5 min). Sets X-Stateway-File-Ref, X-Stateway-Filename (percent-encoded UTF-8) and X-Stateway-Mime-Type headers." } }, "/v1/instances/{id}/variables/{var_name}": { "delete": { "tags": [ "Files" ], "description": "Deletes a file_ref variable on demand (LGPD/GDPR). Removes the object from storage, replaces the variable with a tombstone and decrements the tenant storage quota. Idempotent: retrying an already-deleted variable returns the same tombstone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "description": "Optional free-text reason for the deletion (1-255 chars); defaults to 'unspecified' when omitted. Stored in the tombstone and the audit log." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "var_name", "required": true } ], "responses": { "200": { "description": "Default Response", "headers": { "X-Stateway-Storage-Used": { "schema": { "type": "string" }, "description": "Total bytes currently used by the tenant in storage, after this operation." }, "X-Stateway-Storage-Quota": { "schema": { "type": "string" }, "description": "Total storage quota (bytes) allotted to the tenant." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "variable_name": { "type": "string", "description": "Instance variable that was deleted." }, "status": { "type": "string", "description": "Always 'deleted'." }, "tombstone": { "type": "object", "additionalProperties": true, "description": "The tombstone value now stored in place of the variable (PRD §3.3)." } } } } } } } }, "400": { "description": "Validation failed: reason is empty or exceeds 255 characters.", "content": { "application/json": { "schema": { "type": "object", "description": "Validation failed: reason is empty or exceeds 255 characters.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Instance, variable, or file reference not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Instance, variable, or file reference not found.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "The variable changed to point at a different file reference while the deletion was in flight; retry the request.", "content": { "application/json": { "schema": { "type": "object", "description": "The variable changed to point at a different file reference while the deletion was in flight; retry the request.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "The variable is not a file variable (NOT_A_FILE_VARIABLE), or its upload has not been confirmed yet (FILE_REF_PENDING).", "content": { "application/json": { "schema": { "type": "object", "description": "The variable is not a file variable (NOT_A_FILE_VARIABLE), or its upload has not been confirmed yet (FILE_REF_PENDING).", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_A_FILE_VARIABLE", "FILE_REF_PENDING" ] }, "message": { "type": "string" }, "details": {} } } } } } } } }, "operationId": "deleteV1Instances_id_Variables_var_name_", "summary": "Deletes a file_ref variable on demand (LGPD/GDPR). Removes the object from storage, replaces the variable with a tombstone and decrements the tenant storage quota. Idempotent: retrying an already-deleted variable returns the same tombstone." } }, "/v1/tasks": { "get": { "tags": [ "Tasks" ], "description": "List human tasks", "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Tasks", "summary": "List human tasks" } }, "/v1/tasks/{id}": { "get": { "tags": [ "Tasks" ], "description": "Get task details", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Tasks_id_", "summary": "Get task details" } }, "/v1/tasks/{id}/claim": { "post": { "tags": [ "Tasks" ], "description": "Claim a task", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Tasks_id_Claim", "summary": "Claim a task" } }, "/v1/tasks/{id}/unclaim": { "post": { "tags": [ "Tasks" ], "description": "Unclaim a task", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Tasks_id_Unclaim", "summary": "Unclaim a task" } }, "/v1/tasks/{id}/complete": { "post": { "tags": [ "Tasks" ], "description": "Complete a task", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Tasks_id_Complete", "summary": "Complete a task" } }, "/v1/tasks/{id}/cancel": { "post": { "tags": [ "Tasks" ], "description": "Cancel a task without advancing the process", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Tasks_id_Cancel", "summary": "Cancel a task without advancing the process" } }, "/v1/tasks/{id}/delegate": { "post": { "tags": [ "Tasks" ], "description": "Delegate a task", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Tasks_id_Delegate", "summary": "Delegate a task" } }, "/v1/instances/{id}/events": { "post": { "tags": [ "Events" ], "description": "Send event to process instance", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Instances_id_Events", "summary": "Send event to process instance" } }, "/v1/events/signal/{signal_name}": { "post": { "tags": [ "Events" ], "description": "Broadcast signal to all waiting instances", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "signal_name", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1EventsSignal_signal_name_", "summary": "Broadcast signal to all waiting instances" } }, "/v1/timers": { "get": { "tags": [ "Timers" ], "description": "List active timer jobs", "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Timers", "summary": "List active timer jobs" } }, "/v1/timers/{id}": { "delete": { "tags": [ "Timers" ], "description": "Cancel a timer job", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Timers_id_", "summary": "Cancel a timer job" } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "description": "Create webhook subscription", "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Webhooks", "summary": "Create webhook subscription" }, "get": { "tags": [ "Webhooks" ], "description": "List webhook subscriptions", "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Webhooks", "summary": "List webhook subscriptions" } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "description": "Get webhook subscription details", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Webhooks_id_", "summary": "Get webhook subscription details" }, "put": { "tags": [ "Webhooks" ], "description": "Update webhook subscription", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "putV1Webhooks_id_", "summary": "Update webhook subscription" }, "delete": { "tags": [ "Webhooks" ], "description": "Delete webhook subscription", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Webhooks_id_", "summary": "Delete webhook subscription" } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "description": "Get webhook delivery history", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Webhooks_id_Deliveries", "summary": "Get webhook delivery history" } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "description": "Send test webhook event", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Webhooks_id_Test", "summary": "Send test webhook event" } }, "/v1/decisions": { "post": { "tags": [ "Decisions" ], "description": "Create a new decision definition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "source_type", "source" ], "properties": { "key": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "source_type": { "type": "string", "enum": [ "json", "yaml", "dmn_xml" ] }, "source": {} } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "number" }, "name": { "type": "string" }, "source_type": { "type": "string" }, "source_hash": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } }, "operationId": "postV1Decisions", "summary": "Create a new decision definition" }, "get": { "tags": [ "Decisions" ], "description": "List decision definitions", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "operationId": "listV1Decisions", "summary": "List decision definitions" } }, "/v1/decisions/{key}": { "get": { "tags": [ "Decisions" ], "description": "Get latest active version of a decision definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Decisions_key_", "summary": "Get latest active version of a decision definition" }, "put": { "tags": [ "Decisions" ], "description": "Create a new version of a decision definition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_type", "source" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "source_type": { "type": "string", "enum": [ "json", "yaml", "dmn_xml" ] }, "source": {} } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "putV1Decisions_key_", "summary": "Create a new version of a decision definition" }, "delete": { "tags": [ "Decisions" ], "description": "Delete a decision definition (soft-delete)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Decisions_key_", "summary": "Delete a decision definition (soft-delete)" } }, "/v1/decisions/{key}/versions": { "get": { "tags": [ "Decisions" ], "description": "List all versions of a decision definition", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Decisions_key_Versions", "summary": "List all versions of a decision definition" } }, "/v1/decisions/{key}/rollback": { "post": { "tags": [ "Decisions" ], "description": "Rollback a decision definition to a previous version", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1 } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1Decisions_key_Rollback", "summary": "Rollback a decision definition to a previous version" } }, "/v1/decisions/{key}/evaluate": { "post": { "tags": [ "Decisions" ], "description": "Evaluate a decision with input variables", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "variables" ], "properties": { "variables": { "type": "object" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "evaluation_id": { "type": "string" }, "decision_key": { "type": "string" }, "decision_version": { "type": "number" }, "decision_hash": { "type": "string", "description": "SHA-256 hash of the decision definition used" }, "matched": { "type": "boolean" }, "rules_matched": { "type": "array", "items": { "type": "string" } }, "matched_rules": { "type": "object", "description": "Full matched rule details with per-input evaluation trace", "properties": { "hit_policy": { "type": "string", "description": "DMN hit policy: UNIQUE, COLLECT, ANY, RULE ORDER, etc." }, "not_matched_count": { "type": "number" }, "matched": { "type": "array", "items": { "type": "object", "properties": { "rule_id": { "type": "string" }, "row_number": { "type": "number" }, "annotation": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true }, "outputs": { "type": "object", "additionalProperties": true } } } } } }, "outputs": { "type": "object", "additionalProperties": true }, "evaluated_at": { "type": "string" } } } } } } } } }, "operationId": "postV1Decisions_key_Evaluate", "summary": "Evaluate a decision with input variables" } }, "/v1/decisions/{key}/evaluations": { "get": { "tags": [ "Decisions" ], "description": "List evaluation history for a decision", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "instance_id", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer" }, "in": "query", "name": "version", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "decisionKey": { "type": "string" }, "decisionVersion": { "type": "number" }, "decisionHash": { "type": "string", "description": "SHA-256 hash of the decision definition at evaluation time" }, "matchedRules": { "type": "object", "additionalProperties": true, "description": "Full rule match trace (hit_policy, matched[], not_matched_count)" }, "outputVariables": { "type": "object", "additionalProperties": true }, "evaluatedAt": { "type": "string" } } } } } } } } } }, "operationId": "listV1Decisions_key_Evaluations", "summary": "List evaluation history for a decision" } }, "/v1/decisions/{key}/evaluations/{eval_id}": { "get": { "tags": [ "Decisions" ], "description": "Get a specific decision evaluation by ID", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "eval_id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "decisionKey": { "type": "string" }, "decisionVersion": { "type": "number" }, "decisionHash": { "type": "string", "description": "SHA-256 hash of the decision definition at evaluation time" }, "inputVariables": { "type": "object", "additionalProperties": true }, "matchedRules": { "type": "object", "additionalProperties": true, "description": "Full rule match trace (hit_policy, matched[], not_matched_count)" }, "outputVariables": { "type": "object", "additionalProperties": true }, "hitPolicy": { "type": "string" }, "evaluatedAt": { "type": "string" } } } } } } } } }, "operationId": "listV1Decisions_key_Evaluations_eval_id_", "summary": "Get a specific decision evaluation by ID" } }, "/v1/tenant/plan": { "post": { "tags": [ "Billing" ], "description": "Request a plan change (triggers Stripe checkout)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "starter", "growth", "scale" ] } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "checkoutUrl": { "type": "string" } } } } } } } } }, "operationId": "postV1TenantPlan", "summary": "Request a plan change (triggers Stripe checkout)" }, "get": { "tags": [ "Billing" ], "description": "Get current plan and subscription details", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string" }, "quotaSops": { "type": "number" }, "quotaResetAt": { "type": "string" }, "stripeSubscriptionId": { "type": "string" } } } } } } } } }, "operationId": "listV1TenantPlan", "summary": "Get current plan and subscription details" } }, "/v1/tenant/usage": { "get": { "tags": [ "Billing" ], "description": "Get current billing period usage", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "properties": { "period": { "type": "string" }, "plan": { "type": "string" }, "planLimit": { "type": "number" }, "totalSops": { "type": "number" }, "remaining": { "type": "number" }, "overageSops": { "type": "number" }, "resetAt": { "type": "string" }, "breakdown": { "type": "object", "additionalProperties": true } } } } } } } } }, "operationId": "listV1TenantUsage", "summary": "Get current billing period usage" } }, "/v1/tenant/invoices": { "get": { "tags": [ "Billing" ], "description": "Get invoice history from Stripe", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "pdfUrl": { "type": "string" } } } } } } } } } }, "operationId": "listV1TenantInvoices", "summary": "Get invoice history from Stripe" } }, "/v1/credentials": { "post": { "tags": [ "Credentials" ], "description": "Create a new named credential (encrypted at rest)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } } } } } } }, "operationId": "postV1Credentials", "summary": "Create a new named credential (encrypted at rest)" }, "get": { "tags": [ "Credentials" ], "description": "List all credentials for the tenant (values are never returned)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "operationId": "listV1Credentials", "summary": "List all credentials for the tenant (values are never returned)" } }, "/v1/credentials/{name}": { "get": { "tags": [ "Credentials" ], "description": "Get credential metadata by name (value is never returned)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "listV1Credentials_name_", "summary": "Get credential metadata by name (value is never returned)" }, "patch": { "tags": [ "Credentials" ], "description": "Update credential value and/or description", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "description": { "type": "string", "nullable": true } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "patchV1Credentials_name_", "summary": "Update credential value and/or description" }, "delete": { "tags": [ "Credentials" ], "description": "Soft-delete a credential", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Credentials_name_", "summary": "Soft-delete a credential" } }, "/v1/sessions": { "post": { "tags": [ "Sessions" ], "description": "Emite um token de sessão efêmero para um usuário final. O session_token é retornado uma única vez.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id", "scope" ], "properties": { "user_id": { "type": "string" }, "user_display": { "type": "string" }, "ttl": { "type": "integer" }, "scope": { "type": "object", "required": [ "definitions" ], "properties": { "definitions": { "type": "array", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "candidate_as_user": { "type": "boolean" }, "can_start": { "type": "boolean" }, "max_concurrent": { "type": "integer", "nullable": true }, "searchable_variables": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] }, { "type": "null" } ] } } } }, "variable_visibility": { "type": "string", "enum": [ "declared", "all" ] } } } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session_id": { "type": "string" }, "session_token": { "type": "string" }, "user_id": { "type": "string" }, "expires_at": { "type": "string" }, "scope": { "type": "object", "additionalProperties": true } } } } } } } } }, "operationId": "postV1Sessions", "summary": "Emite um token de sessão efêmero para um usuário final. O session_token é retornado uma única vez." } }, "/v1/sessions/{id}": { "get": { "tags": [ "Sessions" ], "description": "Retorna metadados de uma sessão ativa. O session_token nunca é retornado.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session_id": { "type": "string" }, "user_id": { "type": "string" }, "user_display": { "type": "string", "nullable": true }, "expires_at": { "type": "string" }, "last_seen_at": { "type": "string", "nullable": true }, "scope": { "type": "object", "additionalProperties": true } } } } } } } } }, "operationId": "listV1Sessions_id_", "summary": "Retorna metadados de uma sessão ativa. O session_token nunca é retornado." }, "delete": { "tags": [ "Sessions" ], "description": "Revoga uma sessão ativa imediatamente.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "deleteV1Sessions_id_", "summary": "Revoga uma sessão ativa imediatamente." } }, "/v1/sessions/{id}/refresh": { "post": { "tags": [ "Sessions" ], "description": "Estende o TTL de uma sessão ativa sem invalidar o token existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ttl" ], "properties": { "ttl": { "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "session_id": { "type": "string" }, "expires_at": { "type": "string" } } } } } } } } }, "operationId": "postV1Sessions_id_Refresh", "summary": "Estende o TTL de uma sessão ativa sem invalidar o token existente." } }, "/v1/monitoring/summary": { "get": { "tags": [ "Monitoring" ], "description": "Get operational metrics for the current tenant", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "instances": { "type": "object", "properties": { "pending": { "type": "number" }, "running": { "type": "number" }, "suspended": { "type": "number" }, "completed": { "type": "number" }, "terminated": { "type": "number" }, "error": { "type": "number" } } }, "humanTasks": { "type": "object", "properties": { "pending": { "type": "number" }, "claimed": { "type": "number" }, "completed": { "type": "number" }, "cancelled": { "type": "number" } } }, "serviceTaskJobs": { "type": "object", "properties": { "pending": { "type": "number" }, "running": { "type": "number" }, "completed": { "type": "number" }, "failed": { "type": "number" }, "timeout": { "type": "number" } } }, "timerJobs": { "type": "object", "properties": { "scheduled": { "type": "number" }, "overdue": { "type": "number" } } }, "webhookDeliveries": { "type": "object", "properties": { "pending": { "type": "number" }, "success": { "type": "number" }, "failed": { "type": "number" } } }, "redis": { "type": "object", "properties": { "webhookStreamLength": { "type": "number" }, "webhookStreamPending": { "type": "number" }, "connectedClients": { "type": "number" }, "usedMemoryBytes": { "type": "number" } } } } } } } } } } }, "operationId": "listV1MonitoringSummary", "summary": "Get operational metrics for the current tenant" } }, "/v1/monitoring/system": { "get": { "tags": [ "Monitoring" ], "description": "Get system-wide aggregated metrics (requires admin scope)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "instances": { "type": "object", "properties": { "pending": { "type": "number" }, "running": { "type": "number" }, "suspended": { "type": "number" }, "completed": { "type": "number" }, "terminated": { "type": "number" }, "error": { "type": "number" } } }, "humanTasks": { "type": "object", "properties": { "pending": { "type": "number" }, "claimed": { "type": "number" }, "completed": { "type": "number" }, "cancelled": { "type": "number" } } }, "serviceTaskJobs": { "type": "object", "properties": { "pending": { "type": "number" }, "running": { "type": "number" }, "completed": { "type": "number" }, "failed": { "type": "number" }, "timeout": { "type": "number" } } }, "timerJobs": { "type": "object", "properties": { "scheduled": { "type": "number" }, "overdue": { "type": "number" } } }, "webhookDeliveries": { "type": "object", "properties": { "pending": { "type": "number" }, "success": { "type": "number" }, "failed": { "type": "number" } } }, "redis": { "type": "object", "properties": { "webhookStreamLength": { "type": "number" }, "webhookStreamPending": { "type": "number" }, "connectedClients": { "type": "number" }, "usedMemoryBytes": { "type": "number" } } }, "tenants": { "type": "number" } } } } } } } } }, "operationId": "listV1MonitoringSystem", "summary": "Get system-wide aggregated metrics (requires admin scope)" } }, "/v1/instances/search": { "post": { "tags": [ "Instances" ], "description": "Search process instances using a structured MQL filter with cursor-based pagination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definitionKey": { "type": "string" }, "definitionVersion": { "oneOf": [ { "type": "string", "enum": [ "latest", "all" ] }, { "type": "integer", "minimum": 1 } ] }, "statusScope": { "anyOf": [ { "type": "string", "enum": [ "active", "completed", "all" ] }, { "type": "array", "items": { "type": "string" } } ] }, "filter": { "type": "object", "additionalProperties": true }, "sort": { "type": "object", "additionalProperties": true }, "page": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "cursor": { "type": [ "string", "null" ] } } }, "projection": { "type": "object", "additionalProperties": true }, "text": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "fulltext", "trigram" ] }, "fields": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "fuzzy": { "type": "boolean" } }, "required": [ "query" ] } } } } } }, "responses": { "200": { "description": "Default Response" } }, "operationId": "postV1InstancesSearch", "summary": "Search process instances using a structured MQL filter with cursor-based pagination" } }, "/v1/audit/verify": { "get": { "tags": [ "Audit" ], "description": "Verify tamper-evident hash chain integrity for a time range", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": true }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "instance_id", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true, "description": "Audit chain verification result. status='valid' means chain is intact; status='tampered' means a hash mismatch was detected.", "properties": { "status": { "type": "string", "enum": [ "valid", "tampered" ], "description": "Result of the integrity check" }, "entries_verified": { "type": "number", "description": "Number of audit entries checked before the result was determined" }, "first_entry_id": { "type": "string", "description": "ID of the first entry in the verified range (present when status=valid and entries_verified > 0)" }, "last_entry_id": { "type": "string", "description": "ID of the last entry in the verified range (present when status=valid)" }, "from": { "type": "string", "description": "Start of the verified time range (present when status=valid)" }, "to": { "type": "string", "description": "End of the verified time range (present when status=valid)" }, "first_broken_entry_id": { "type": "string", "description": "ID of the first entry where hash mismatch was detected (present when status=tampered)" }, "break_detected_at": { "type": "string", "description": "Timestamp of the first tampered entry (present when status=tampered)" }, "detail": { "type": "string", "description": "Human-readable description of the tampering (present when status=tampered)" } } } } } } } } }, "operationId": "listV1AuditVerify", "summary": "Verify tamper-evident hash chain integrity for a time range" } }, "/internal/sessions/resolve": { "get": { "responses": { "200": { "description": "Default Response" } }, "operationId": "listInternalSessionsResolve", "summary": "GET /internal/sessions/resolve" } }, "/internal/instances": { "post": { "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalInstances", "summary": "POST /internal/instances" } }, "/internal/tasks/{id}/claim": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalTasks_id_Claim", "summary": "POST /internal/tasks/{id}/claim" } }, "/internal/tasks/{id}/unclaim": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalTasks_id_Unclaim", "summary": "POST /internal/tasks/{id}/unclaim" } }, "/internal/tasks/{id}/complete": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalTasks_id_Complete", "summary": "POST /internal/tasks/{id}/complete" } }, "/internal/instances/{id}/events": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalInstances_id_Events", "summary": "POST /internal/instances/{id}/events" } }, "/internal/decisions/{key}/evaluate": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalDecisions_key_Evaluate", "summary": "POST /internal/decisions/{key}/evaluate" } }, "/internal/instances/search": { "post": { "responses": { "200": { "description": "Default Response" } }, "operationId": "postInternalInstancesSearch", "summary": "POST /internal/instances/search" } } }, "servers": [ { "url": "http://localhost:3000", "description": "Development" } ], "tags": [ { "name": "Health", "description": "Health check endpoints" }, { "name": "Definitions", "description": "Process definitions CRUD" }, { "name": "Instances", "description": "Process instance management" }, { "name": "Tasks", "description": "Human task management" }, { "name": "Events", "description": "External events" }, { "name": "Timers", "description": "Timer jobs" }, { "name": "Files", "description": "File variables: upload slots, download and deletion" }, { "name": "Webhooks", "description": "Webhook subscriptions" }, { "name": "Auth", "description": "API Key management" }, { "name": "Tenant", "description": "Tenant management" }, { "name": "Decisions", "description": "Decision Model (DMM) management" }, { "name": "Billing", "description": "Billing and usage" }, { "name": "Credentials", "description": "Encrypted credential storage" }, { "name": "Sessions", "description": "Frontend session tokens" }, { "name": "Monitoring", "description": "Operational metrics" } ] }