{ "openapi": "3.1.0", "info": { "title": "GetRatchet API", "version": "1.0.0", "description": "Versioned API for runs, durable tools, recovery, and developer-owned workers." }, "servers": [ { "url": "https://getratchet.app" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Use an organization API key with the scope required by the operation." } } }, "paths": { "/api/v1/audit": { "get": { "operationId": "get_audit", "summary": "List organization audit events", "tags": [ "Audit" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "events": [], "nextCursor": null } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid audit query" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "targetType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "targetId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } } ], "description": "Requires an administrator key. Results are scoped to the key's organization and omit payloads and secrets.", "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/context": { "get": { "operationId": "get_context", "summary": "Verify credentials and list authorized project/environment identifiers", "tags": [ "Context" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "organizationId": "org_example", "scopes": [ "INGEST" ], "projectId": "project_example", "environmentId": "environment_example", "projects": [ { "id": "project_example", "environments": [ { "id": "environment_example" } ] } ] } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "x-required-scope": "READ", "x-accepted-scopes": [ "READ", "INGEST", "WORKER", "ADMIN" ], "description": "Accepts any valid READ, INGEST, WORKER or administrator credential. Returns only organization/scope and authorized project/environment identifiers. No key secret or account details are returned.", "x-console-auth": false } }, "/api/v1/endpoints": { "get": { "operationId": "get_endpoints", "summary": "List endpoint policies", "tags": [ "Endpoints" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "endpoints": [] } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "x-required-scope": "READ", "x-console-auth": false } }, "/api/v1/endpoints/{id}/pause": { "post": { "operationId": "post_endpoints_id_pause", "summary": "Pause an endpoint", "tags": [ "Endpoints" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "paused": true, "queuedWork": "held without consuming an attempt", "inFlight": "may finish" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/endpoints/{id}/policy": { "get": { "operationId": "get_endpoints_id_policy", "summary": "Get endpoint policy", "tags": [ "Endpoints" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "endpoint": { "id": "endpoint_example", "policyVersion": 1, "policyPreset": "CUSTOM", "maxConcurrent": 4, "retryPolicy": { "preset": "CUSTOM", "maxAttempts": 6, "initialDelayMs": 10000, "multiplier": 2, "maxDelayMs": 600000, "jitterPercent": 20 } } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true, "description": "Endpoint retry policy: STANDARD (5 attempts, 30s initial, 15m cap), AGGRESSIVE (8, 5s, 5m), RELAXED (3, 120s, 30m), or CUSTOM. Built-ins double with ±20% jitter. The endpoint response includes retryPolicy (complete custom policy or null)." }, "put": { "operationId": "put_endpoints_id_policy", "summary": "Update endpoint policy", "tags": [ "Endpoints" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "endpoint": { "id": "endpoint_example", "policyVersion": 2, "policyPreset": "CUSTOM", "retryPolicy": { "preset": "CUSTOM", "maxAttempts": 6, "initialDelayMs": 10000, "multiplier": 2, "maxDelayMs": 600000, "jitterPercent": 20 } }, "note": "Existing jobs retain timeout, retry preset, attempt limit and due times; live concurrency and rate gates apply at claim" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid service policy" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Not found or policy version changed" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "defaultTimeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 }, "maxConcurrent": { "type": "integer", "minimum": 1, "maximum": 100 }, "rateLimitPerMinute": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "preset": { "enum": [ "STANDARD", "AGGRESSIVE", "RELAXED" ] } }, "required": [ "expectedVersion", "defaultTimeoutMs", "maxConcurrent", "rateLimitPerMinute", "preset" ], "additionalProperties": false }, { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "defaultTimeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 }, "maxConcurrent": { "type": "integer", "minimum": 1, "maximum": 100 }, "rateLimitPerMinute": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "preset": { "const": "CUSTOM" }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Includes the first execution." }, "initialDelayMs": { "type": "integer", "minimum": 1000, "maximum": 1800000 }, "multiplier": { "type": "number", "minimum": 1, "maximum": 4 }, "maxDelayMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "description": "Must be greater than or equal to initialDelayMs (validated by the server). Cap before jitter." }, "jitterPercent": { "type": "number", "minimum": 0, "maximum": 50 } }, "required": [ "expectedVersion", "defaultTimeoutMs", "maxConcurrent", "rateLimitPerMinute", "preset", "maxAttempts", "initialDelayMs", "multiplier", "maxDelayMs", "jitterPercent" ], "additionalProperties": false, "description": "Complete custom policy. maxDelayMs >= initialDelayMs. Snapshot at enqueue; later policy edits never change queued jobs or their dueAt." } ] }, "example": { "expectedVersion": 1, "defaultTimeoutMs": 30000, "maxConcurrent": 4, "rateLimitPerMinute": null, "preset": "CUSTOM", "maxAttempts": 6, "initialDelayMs": 10000, "multiplier": 2, "maxDelayMs": 600000, "jitterPercent": 20 } } } }, "x-required-scope": "ADMIN", "x-console-auth": true, "description": "Endpoint retry policy: STANDARD (5 attempts, 30s initial, 15m cap), AGGRESSIVE (8, 5s, 5m), RELAXED (3, 120s, 30m), or CUSTOM. Built-ins double with ±20% jitter. The endpoint response includes retryPolicy (complete custom policy or null)." } }, "/api/v1/endpoints/{id}/resume": { "post": { "operationId": "post_endpoints_id_resume", "summary": "Resume an endpoint", "tags": [ "Endpoints" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "paused": false } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/executions/{id}": { "patch": { "operationId": "patch_executions_id", "summary": "Finish a synchronous execution", "tags": [ "Executions" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid execution result" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "Output must be JSON and at most 64 KiB" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Execution already finished" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "output": { "type": "object", "properties": { "customerId": { "type": "string" } }, "required": [ "customerId" ], "additionalProperties": true } }, "required": [ "status", "output" ], "additionalProperties": true }, "example": { "status": "SUCCEEDED", "output": { "customerId": "customer-42" } } } } }, "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/exports/audit": { "get": { "operationId": "get_exports_audit", "summary": "Export a page of audit events", "tags": [ "Exports" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "events": [], "nextCursor": null } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "targetType", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "targetId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } } ], "description": "Requires an administrator key. Each JSON download contains at most 100 organization audit events and a nextCursor for the next page.", "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/exports/runs": { "get": { "operationId": "get_exports_runs", "summary": "Export a page of redacted run summaries", "tags": [ "Exports" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "runs": [], "nextCursor": null, "exportedAt": "2026-09-26T12:00:00.000Z" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Run name or ID substring", "schema": { "type": "string", "maxLength": 100 } }, { "name": "runId", "in": "query", "required": false, "description": "Exact run ID", "schema": { "type": "string", "maxLength": 64 } }, { "name": "projectId", "in": "query", "required": false, "description": "Exact project ID", "schema": { "type": "string", "maxLength": 100 } }, { "name": "environmentId", "in": "query", "required": false, "description": "Exact environment ID", "schema": { "type": "string", "maxLength": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Run status", "schema": { "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ] } }, { "name": "isTest", "in": "query", "required": false, "description": "Filter synthetic test runs", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "service", "in": "query", "required": false, "description": "Service name substring", "schema": { "type": "string", "maxLength": 120 } }, { "name": "tool", "in": "query", "required": false, "description": "Tool name substring", "schema": { "type": "string", "maxLength": 120 } }, { "name": "handlerVersion", "in": "query", "required": false, "description": "Exact handler version", "schema": { "type": "string", "maxLength": 40 } }, { "name": "idempotencyKey", "in": "query", "required": false, "description": "Exact step idempotency key", "schema": { "type": "string", "maxLength": 255 } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO date or timestamp", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO date or timestamp", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Last run ID from the previous page", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size; default 25", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "description": "Requires an administrator key. Each JSON download contains at most 100 run summaries and a nextCursor for the next page; names and tool payloads are excluded.", "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/health": { "get": { "operationId": "get_health", "summary": "Get organization queue, worker, and circuit health", "tags": [ "Health" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "platform": "operational", "workload": "normal", "queueDepth": 0, "oldestQueuedAt": null, "workersRegistered": 1, "workersOnline": 1, "openCircuits": 0, "pausedServices": 0, "checkedAt": "2026-09-26T12:00:00.000Z" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "example": { "error": "Health data unavailable" } } } } }, "x-required-scope": "READ", "x-console-auth": false } }, "/api/v1/jobs/{id}/cancel": { "post": { "operationId": "post_jobs_id_cancel", "summary": "Cancel a durable job", "tags": [ "Jobs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "state": "CANCELLED" } } } }, "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "state": "CANCEL_REQUESTED", "message": "The in-flight handler may finish before it observes cancellation" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Job already finished" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/recovery": { "get": { "operationId": "get_recovery", "summary": "List bulk recovery plans", "tags": [ "Recovery" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "jobs": [] } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "x-required-scope": "ADMIN", "x-console-auth": true }, "post": { "operationId": "post_recovery", "summary": "Create a bulk recovery plan", "tags": [ "Recovery" ], "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "job": { "id": "recovery_example", "state": "QUEUED", "total": 4, "processed": 0 } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid recovery filters or duplicate-risk acknowledgement" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "No eligible exhausted steps" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "More than 500 steps match; narrow the filters" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledgeDuplicateRisk": { "type": "boolean" }, "projectId": { "type": "string", "maxLength": 100 }, "environmentId": { "type": "string", "maxLength": 100 }, "failureType": { "type": "string", "enum": [ "rate_limit", "timeout", "authorization", "schema", "unavailable" ], "description": "Coarse case-insensitive match against the saved final error text." }, "runId": { "type": "string", "maxLength": 120 }, "service": { "type": "string", "maxLength": 120 }, "tool": { "type": "string", "maxLength": 120 }, "handlerVersion": { "type": "string", "maxLength": 40 }, "failureText": { "type": "string", "maxLength": 80 }, "includeCancelled": { "type": "boolean", "default": false }, "ratePerMinute": { "type": "integer", "minimum": 1, "maximum": 60, "default": 10 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "acknowledgeDuplicateRisk" ], "additionalProperties": true }, "example": { "acknowledgeDuplicateRisk": true } } } }, "description": "Requires administrator access and duplicate-risk acknowledgement. Filters are intersected within the key's organization. Failure categories are coarse matches on the saved final error, not a guaranteed root-cause classification.", "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/recovery/{id}": { "delete": { "operationId": "delete_recovery_id", "summary": "Cancel a bulk recovery plan", "tags": [ "Recovery" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "state": "CANCELLED" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Not found or already finished" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true }, "get": { "operationId": "get_recovery_id", "summary": "Get a bulk recovery plan", "tags": [ "Recovery" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "job": { "id": "recovery_example", "state": "COMPLETED", "total": 4, "processed": 4 } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/runs": { "get": { "operationId": "get_runs", "summary": "List recent runs", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "runs": [], "nextCursor": null } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Run name or ID substring", "schema": { "type": "string", "maxLength": 100 } }, { "name": "runId", "in": "query", "required": false, "description": "Exact run ID", "schema": { "type": "string", "maxLength": 64 } }, { "name": "projectId", "in": "query", "required": false, "description": "Exact project ID", "schema": { "type": "string", "maxLength": 100 } }, { "name": "environmentId", "in": "query", "required": false, "description": "Exact environment ID", "schema": { "type": "string", "maxLength": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Run status", "schema": { "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ] } }, { "name": "isTest", "in": "query", "required": false, "description": "Filter synthetic test runs", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "service", "in": "query", "required": false, "description": "Service name substring", "schema": { "type": "string", "maxLength": 120 } }, { "name": "tool", "in": "query", "required": false, "description": "Tool name substring", "schema": { "type": "string", "maxLength": 120 } }, { "name": "handlerVersion", "in": "query", "required": false, "description": "Exact handler version", "schema": { "type": "string", "maxLength": 40 } }, { "name": "idempotencyKey", "in": "query", "required": false, "description": "Exact step idempotency key", "schema": { "type": "string", "maxLength": 255 } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO date or timestamp", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO date or timestamp", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Last run ID from the previous page", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size; default 25", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "x-required-scope": "READ", "x-console-auth": false }, "post": { "operationId": "post_runs", "summary": "Start a run", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "run": { "id": "run_example", "name": "customer-onboarding", "status": "RUNNING" } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid run name" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Run scope does not match key" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "projectId": { "type": "string", "description": "Supply with environmentId" }, "environmentId": { "type": "string", "description": "Supply with projectId" } }, "required": [ "name" ], "additionalProperties": true }, "example": { "name": "customer-onboarding" } } } }, "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/runs/{id}": { "get": { "operationId": "get_runs_id", "summary": "Get a run and its steps", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "run": { "id": "run_example", "name": "customer-onboarding", "status": "SUCCEEDED", "steps": [] } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "READ", "x-console-auth": false, "description": "Steps include durableJob state, persisted dueAt, attemptCount, maxAttempts, policyPreset and retryPolicy snapshot; encrypted input and lease credentials are not returned." }, "patch": { "operationId": "patch_runs_id", "summary": "Finish a run", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "run": { "id": "run_example", "status": "SUCCEEDED" }, "pendingSteps": 0 } } } }, "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "run": { "id": "run_example", "status": "RUNNING", "finishRequested": true }, "pendingSteps": 1 } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid status" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Run already finished" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] } }, "required": [ "status" ], "additionalProperties": true }, "example": { "status": "SUCCEEDED" } } } }, "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/runs/{id}/enqueue": { "post": { "operationId": "post_runs_id_enqueue", "summary": "Enqueue a durable tool call", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "deduplicated": true, "stepId": "step_example", "status": "SUCCEEDED", "output": { "sent": true } } } } }, "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "stepId": "step_example", "jobId": "job_example" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid durable tool request" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "Input must be JSON and at most 64 KiB" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Run not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Idempotency key belongs to another run" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "endpoint": { "type": "string" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255 }, "input": { "description": "Any JSON value up to 64 KiB; validated against a published contract when present." }, "contractVersion": { "type": "string" }, "timeoutMs": { "type": "integer", "minimum": 100 }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "after": { "type": "object", "properties": { "stepId": { "type": "string" }, "on": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] } }, "required": [ "stepId", "on" ], "additionalProperties": false, "description": "Wait for an earlier durable step in the same run; FAILED schedules a fallback." } }, "required": [ "name", "version", "endpoint", "idempotencyKey", "input" ], "additionalProperties": true }, "example": { "name": "send_welcome_email", "version": "1", "endpoint": "email", "idempotencyKey": "welcome:customer-42", "input": { "customerId": "customer-42" } } } } }, "description": "The idempotency key is unique per organization. Reuse it for safe transport retries; the handler still needs destination-side idempotency for irreversible effects. The complete policy is snapshotted: selected contract overrides endpoint; explicit maxAttempts overrides only the attempt count. Existing jobs and due times never change when policies change. Delivery is at least once: use destination-side idempotency to prevent duplicate side effects.", "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/runs/{id}/steps": { "post": { "operationId": "post_runs_id_steps", "summary": "Record a synchronous step", "tags": [ "Runs" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "deduplicated": true, "stepId": "step_example", "status": "SUCCEEDED", "output": {} } } } }, "201": { "description": "Created", "content": { "application/json": { "example": { "stepId": "step_example", "executionId": "execution_example", "attempt": 1 } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid step" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "Input must be JSON and at most 64 KiB" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Run not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Idempotency key belongs to another run" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "example": { "error": "Circuit open" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "string" }, "idempotencyKey": { "type": "string" }, "input": { "type": "object", "properties": { "customerId": { "type": "string" } }, "required": [ "customerId" ], "additionalProperties": true } }, "required": [ "name", "endpoint", "idempotencyKey", "input" ], "additionalProperties": true }, "example": { "name": "lookup_customer", "endpoint": "crm", "idempotencyKey": "lookup:customer-42", "input": { "customerId": "customer-42" } } } } }, "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/steps/{id}/attempts": { "post": { "operationId": "post_steps_id_attempts", "summary": "Start another synchronous attempt", "tags": [ "Steps" ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "executionId": "execution_example", "attempt": 2 } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Step is not retrying" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "example": { "error": "Circuit open or probe in progress" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "INGEST", "x-console-auth": false } }, "/api/v1/steps/{id}/replay": { "get": { "operationId": "get_steps_id_replay", "summary": "Preview replay risks", "tags": [ "Steps" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "step": { "id": "step_example", "status": "FAILED" }, "replayable": true, "upgrades": [], "warning": "At-least-once execution can repeat an external side effect." } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-required-scope": "ADMIN", "x-console-auth": true }, "post": { "operationId": "post_steps_id_replay", "summary": "Replay a step", "tags": [ "Steps" ], "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "state": "QUEUED", "jobId": "job_example", "handlerVersion": "1", "replayId": "replay_example", "nextAttempt": 2 } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Explicit duplicate-risk acknowledgement and valid replay options are required" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Not found" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Replay forbidden by published tool contract" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "A step with dependent branches cannot be replayed" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledgeDuplicateRisk": { "type": "boolean" }, "maxAttempts": { "type": "integer" }, "reason": { "type": "string" }, "targetContractVersion": { "type": "string", "maxLength": 40, "description": "Published contract for a different handler version. The saved input must match its input schema." }, "expectedHandlerVersion": { "type": "string", "maxLength": 40, "description": "Current version shown by replay preview; required for a version change." }, "acknowledgeVersionChange": { "type": "boolean", "enum": [ true ], "description": "Required for a version change after reviewing compatibility and duplicate-side-effect risk." } }, "required": [ "acknowledgeDuplicateRisk", "maxAttempts", "reason" ], "additionalProperties": true }, "example": { "acknowledgeDuplicateRisk": true, "maxAttempts": 1, "reason": "Provider incident resolved" } } } }, "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/tools": { "get": { "operationId": "get_tools", "summary": "List published tool contracts", "tags": [ "Tools" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "tools": [] } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } } }, "x-required-scope": "READ", "x-console-auth": false }, "post": { "operationId": "post_tools", "summary": "Publish a tool contract", "tags": [ "Tools" ], "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "tool": { "id": "tool_example", "name": "classify_sample", "contractVersion": "1", "handlerVersion": "1" } } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid tool contract" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Tool contract version already exists" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contractVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "handlerVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "owner": { "type": "string", "minLength": 1, "maxLength": 120 }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000, "default": 30000 }, "dataClassification": { "enum": [ "PUBLIC", "INTERNAL", "SENSITIVE" ], "default": "INTERNAL" }, "replaySafety": { "enum": [ "SAFE", "CAUTION", "FORBIDDEN" ], "default": "CAUTION" }, "retryPreset": { "enum": [ "STANDARD", "AGGRESSIVE", "RELAXED" ], "default": "STANDARD" } }, "required": [ "name", "contractVersion", "handlerVersion", "description", "owner", "inputSchema", "outputSchema" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "contractVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "handlerVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "owner": { "type": "string", "minLength": 1, "maxLength": 120 }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000, "default": 30000 }, "dataClassification": { "enum": [ "PUBLIC", "INTERNAL", "SENSITIVE" ], "default": "INTERNAL" }, "replaySafety": { "enum": [ "SAFE", "CAUTION", "FORBIDDEN" ], "default": "CAUTION" }, "retryPreset": { "const": "CUSTOM" }, "retryPolicy": { "type": "object", "properties": { "preset": { "const": "CUSTOM" }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Includes the first execution." }, "initialDelayMs": { "type": "integer", "minimum": 1000, "maximum": 1800000 }, "multiplier": { "type": "number", "minimum": 1, "maximum": 4 }, "maxDelayMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "description": "Must be greater than or equal to initialDelayMs (validated by the server). Cap before jitter." }, "jitterPercent": { "type": "number", "minimum": 0, "maximum": 50 } }, "required": [ "preset", "maxAttempts", "initialDelayMs", "multiplier", "maxDelayMs", "jitterPercent" ], "additionalProperties": false, "description": "Complete custom policy. maxDelayMs >= initialDelayMs. Snapshot at enqueue; later policy edits never change queued jobs or their dueAt.", "x-constraint": "maxDelayMs >= initialDelayMs" } }, "required": [ "name", "contractVersion", "handlerVersion", "description", "owner", "inputSchema", "outputSchema", "retryPreset", "retryPolicy" ], "additionalProperties": false } ] }, "example": { "name": "classify_sample", "contractVersion": "1", "handlerVersion": "1", "description": "Classify a sample", "owner": "platform-team", "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, "outputSchema": { "type": "object", "properties": { "label": { "type": "string" } } }, "replaySafety": "SAFE" } } } }, "x-required-scope": "ADMIN", "x-console-auth": false, "description": "Immutable versioned contract. CUSTOM requires a complete retryPolicy; built-in presets forbid it. The selected contract overrides the endpoint retry policy. Explicit enqueue maxAttempts overrides only its attempt count." } }, "/api/v1/tools/test": { "post": { "operationId": "post_tools_test", "summary": "Queue one rate-limited synthetic test of a SAFE tool contract", "tags": [ "Tools" ], "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Accepted or pending", "content": { "application/json": { "example": { "runId": "run_example", "stepId": "step_example", "jobId": "job_example" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid synthetic test request" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "Input must be JSON and at most 64 KiB" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Test scope does not match key" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Published tool contract version not found" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Synthetic execution requires a SAFE tool contract. Register a separate safe test handler for tools with side effects." } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "example": { "error": "Rate limit exceeded" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contractVersion": { "type": "string" }, "projectId": { "type": "string" }, "environmentId": { "type": "string" }, "input": { "description": "Any JSON value up to 64 KiB that matches the selected contract." } }, "required": [ "name", "contractVersion", "projectId", "environmentId", "input" ], "additionalProperties": true }, "example": { "name": "classify_sample", "contractVersion": "1", "projectId": "project-id", "environmentId": "environment-id", "input": { "text": "sample" } } } } }, "description": "Requires administrator access. Only contracts marked SAFE can be tested. Creates a separate isTest run with one attempt, limited to 10 requests per organization per hour. A developer-owned worker must register the exact handler version.", "x-required-scope": "ADMIN", "x-console-auth": true } }, "/api/v1/workers/claim": { "post": { "operationId": "post_workers_claim", "summary": "Claim the next due job", "tags": [ "Workers" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "job": { "jobId": "job_example", "toolName": "send_welcome_email", "toolVersion": "1", "input": { "customerId": "customer-42" }, "leaseToken": 3 } } } } }, "204": { "description": "No due job" }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid worker ID" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "error": "Worker is not registered to this key" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "workerId": { "type": "string" } }, "required": [ "workerId" ], "additionalProperties": true }, "example": { "workerId": "worker-example-001" } } } }, "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key.", "x-required-scope": "WORKER", "x-console-auth": false } }, "/api/v1/workers/jobs/{id}/heartbeat": { "post": { "operationId": "post_workers_jobs_id_heartbeat", "summary": "Renew a job lease", "tags": [ "Workers" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "accepted": true, "cancelRequested": false } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid heartbeat" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "accepted": false, "cancelRequested": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "workerId": { "type": "string" }, "leaseToken": { "type": "integer" } }, "required": [ "workerId", "leaseToken" ], "additionalProperties": true }, "example": { "workerId": "worker-example-001", "leaseToken": 3 } } } }, "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key.", "x-required-scope": "WORKER", "x-console-auth": false } }, "/api/v1/workers/jobs/{id}/report": { "post": { "operationId": "post_workers_jobs_id_report", "summary": "Report a fenced job result", "tags": [ "Workers" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "accepted": true } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid result" } } } }, "413": { "description": "Request too large", "content": { "application/json": { "example": { "error": "Output must be JSON and at most 64 KiB" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "accepted": false } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "workerId": { "type": "string", "minLength": 8, "maxLength": 120 }, "leaseToken": { "type": "integer", "minimum": 1 }, "status": { "const": "SUCCEEDED" }, "output": {}, "retryAfterMs": false }, "required": [ "workerId", "leaseToken", "status" ], "additionalProperties": true }, { "type": "object", "properties": { "workerId": { "type": "string", "minLength": 8, "maxLength": 120 }, "leaseToken": { "type": "integer", "minimum": 1 }, "status": { "const": "FAILED" }, "error": { "type": "string", "minLength": 1, "maxLength": 2000 }, "retryable": { "const": false }, "retryAfterMs": false }, "required": [ "workerId", "leaseToken", "status", "error", "retryable" ], "additionalProperties": true }, { "type": "object", "properties": { "workerId": { "type": "string", "minLength": 8, "maxLength": 120 }, "leaseToken": { "type": "integer", "minimum": 1 }, "status": { "const": "FAILED" }, "error": { "type": "string", "minLength": 1, "maxLength": 2000 }, "retryable": { "const": true, "default": true }, "retryAfterMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "description": "Minimum delay after a retryable failure. dueAt uses max(jittered policy delay, retryAfterMs), capped at 24 hours. No jitter is applied to this minimum." } }, "required": [ "workerId", "leaseToken", "status", "error" ], "additionalProperties": true } ] }, "example": { "workerId": "worker-example-001", "leaseToken": 3, "status": "SUCCEEDED", "output": { "providerMessageId": "msg_example" } } } } }, "description": "Fenced worker result. Unknown handler errors default to retryable. The server does not classify messages or HTTP status codes. Non-retryable errors exhaust immediately. Synthetic tests still have one attempt.", "x-required-scope": "WORKER", "x-console-auth": false } }, "/api/v1/workers/register": { "post": { "operationId": "post_workers_register", "summary": "Register a worker and handler versions", "tags": [ "Workers" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "workerId": "worker-example-001", "heartbeatAt": "2026-09-26T12:00:00.000Z" } } } }, "401": { "description": "Missing, invalid or insufficient credentials", "content": { "application/json": { "example": { "error": "Unauthorized" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "error": "Invalid worker registration" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "error": "Key is not authorized for every handler version" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "example": { "error": "Worker ID belongs to another key" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "workerId": { "type": "string" }, "capacity": { "type": "integer" }, "handlers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": true } } }, "required": [ "workerId", "capacity", "handlers" ], "additionalProperties": true }, "example": { "workerId": "worker-example-001", "capacity": 4, "handlers": [ { "name": "send_welcome_email", "version": "1" } ] } } } }, "description": "Requires a WORKER scoped key. Worker IDs are bound to their registering API key.", "x-required-scope": "WORKER", "x-console-auth": false } } } }