{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/integrations.revenexx.com" } ], "info": { "name": "Integrations Service API", "_postman_id": "fba59a25-1ada-423c-86c8-4ec28b35a9c0", "description": "API for the revenexx Integration Studio \u2014 connects Revenue Cloud to external systems (ERP, PIM, CRM) via Temporal workflows.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Audit Log", "description": "\nRead access to the append-only audit trail (credential \/ secret \/ workflow \/\ntrigger create-edit-delete, plus workflow run start\/finished\/failed). Two\nplanes: the public feed is auto-scoped to the caller's org + tenant; the\nadmin feed (registered under `v1\/admin`) filters all three identity fields\noptionally. Results are newest-first and cursor-paginated.", "item": [ { "name": "List audit entries (public)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/audit-logs", "query": [ { "key": "sub", "value": "289347298347", "description": "optional Filter by acting user subject.", "disabled": false }, { "key": "resource_type", "value": "workflow", "description": "optional Filter by resource type (credential, secret, workflow, trigger, workflow_run).", "disabled": false }, { "key": "action", "value": "create", "description": "optional Filter by action (create, update, delete, run.started, run.finished, run.failed).", "disabled": false }, { "key": "limit", "value": "50", "description": "optional Page size (1\u2013100, default 50).", "disabled": false }, { "key": "cursor", "value": "eyJpZCI6NDJ9", "description": "optional Opaque pagination cursor from a previous response.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/audit-logs?sub=289347298347&resource_type=workflow&action=create&limit=50&cursor=eyJpZCI6NDJ9" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the audit entries for the caller's org + tenant, newest first.\nOptionally narrowed by `sub` (actor), `resource_type` and `action`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 42, \"org_id\": \"acme-org\", \"tenant_id\": \"acme-production\", \"actor_sub\": \"289347298347\", \"via_system\": false, \"channel\": \"api\", \"action\": \"create\", \"resource_type\": \"workflow\", \"resource_id\": \"1\", \"metadata\": {\"name\": \"Sync orders\"}, \"created_at\": \"2026-06-18T10:00:00Z\"}], \"meta\": {\"per_page\": 50, \"next_cursor\": null, \"prev_cursor\": null}}", "name": "Success" } ] } ] }, { "name": "Auth", "description": "\nEndpoints for verifying authentication and tenant context.", "item": [ { "name": "Get authenticated user info", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/me", "query": [], "raw": "{{baseUrl}}\/api\/v1\/me" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns full user profile, resolved tenant context, and raw token claims.\nUseful for debugging authentication and understanding which data Zitadel provides." }, "response": [ { "header": [], "code": 200, "body": "{\n \"user\": {\"id\": 1, \"zitadel_id\": \"289347298347\", \"email\": \"user@acme.com\", \"name\": \"Jane Doe\"},\n \"context\": {\"tenant_id\": \"acme-production\", \"active_plane\": \"public\", \"roles\": [\"admin\", \"user\"]},\n \"claims\": {\"iss\": \"https:\/\/id.revenexx.com\", \"sub\": \"289347298347\", \"aud\": [\"project-id\"]}\n}", "name": "Success" }, { "header": [], "code": 401, "body": "{\n \"message\": \"Unauthenticated.\"\n}", "name": "Missing or invalid token" } ] } ] }, { "name": "Credential Types", "description": "\nRead-only catalogue of the credential types registered via node packages.\nDrives the credential form (fields + validation) and the `credentials-ref`\ntype picker in the editor. Globally registered, not tenant-scoped.", "item": [ { "name": "List credential types", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credential-types", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credential-types" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the latest registered version of each credential type." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"slug\": \"revenexx:smtp\", \"version\": \"1.0.0\", \"name\": \"SMTP\", \"description\": \"Send mail over SMTP\", \"icon\": null, \"images\": [{\"src\": \"https:\/\/api.example.com\/v1\/node-packages\/images\/2b1c0000-0000-4000-8000-000000000000?expires=1750000000&signature=abcdef\", \"alt\": {\"en\": \"SMTP logo\"}, \"title\": {\"en\": \"SMTP\"}, \"category\": \"logo\"}], \"auth_kind\": \"secret\", \"fields\": []}]}", "name": "Success" } ] }, { "name": "Show a credential type", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credential-types\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credential-types\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Asmtp", "description": "Namespaced credential type slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the latest registered version of the credential type identified\nby its namespaced slug." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"slug\": \"revenexx:smtp\", \"version\": \"1.0.0\", \"name\": \"SMTP\", \"description\": \"Send mail over SMTP\", \"icon\": null, \"images\": [{\"src\": \"https:\/\/api.example.com\/v1\/node-packages\/images\/2b1c0000-0000-4000-8000-000000000000?expires=1750000000&signature=abcdef\", \"alt\": {\"en\": \"SMTP logo\"}, \"title\": {\"en\": \"SMTP\"}, \"category\": \"logo\"}], \"auth_kind\": \"secret\", \"fields\": []}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] } ] }, { "name": "Credentials", "description": "\nTenant-scoped credential instances of a registered {@see CredentialType}.\nThe encrypted `config` \/ `durable_creds` blobs are never returned. Runtime\nresolution happens in the broker, not here \u2014 this controller only stores and\nproxies the on-demand connection test.", "item": [ { "name": "OAuth redirect callback (public)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/oauth\/callback", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/oauth\/callback" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "The provider redirects the user's browser here with `code` + `state`.\nUnauthenticated by necessity \u2014 the single-use `state` (looked up in the\ncache) is the CSRF protection and carries the tenant + PKCE verifier.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"status\": \"connected\", \"credential_id\": 1}", "name": "Connected" }, { "header": [], "code": 400, "body": "{\"message\": \"Invalid or expired OAuth state.\"}", "name": "Missing or invalid state" } ] }, { "name": "List credentials", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials", "query": [ { "key": "type", "value": "revenexx%3Asmtp", "description": "Filter by credential type slug.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/credentials?type=revenexx%3Asmtp" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the current tenant's credential instances, optionally filtered to\na single credential type via `?type={slug}`. Secrets are never exposed." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 1, \"tenant_id\": \"acme-production\", \"credential_type_slug\": \"revenexx:smtp\", \"name\": \"Production SMTP\", \"status\": \"active\", \"public_config\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Create a credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"credential_type_slug\":\"revenexx:smtp\",\"name\":\"Mailpit\",\"config\":{\"host\":\"smtp.example.com\",\"port\":587,\"username\":\"mailer\",\"password\":\"sekret\"}}" }, "description": "Validates the submitted `config` against the credential type's declared\nfields, then stores it encrypted. Returns 201 with the masked instance." }, "response": [ { "header": [], "code": 201, "body": "{\"id\": 1, \"tenant_id\": \"acme-production\", \"credential_type_slug\": \"revenexx:smtp\", \"name\": \"Production SMTP\", \"status\": \"active\", \"public_config\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Created" }, { "header": [], "code": 422, "body": "{\"message\": \"The given data was invalid.\", \"errors\": {\"config\": [\"...\"]}}", "name": "Validation failed" } ] }, { "name": "Test an unsaved credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/test" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"credential_type_slug\":\"revenexx:smtp\",\"config\":{\"host\":\"smtp.example.com\",\"port\":587,\"username\":\"mailer\",\"password\":\"sekret\"}}" }, "description": "Runs the broker connection test against an inline type + config, before\nthe instance is persisted. Non-blocking." }, "response": [ { "header": [], "code": 200, "body": "{\"ok\": true, \"message\": null}", "name": "Tested" }, { "header": [], "code": 200, "body": "{\"ok\": false, \"message\": \"Invalid auth key\"}", "name": "Failed" } ] }, { "name": "Show a credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4f2a-7d3e-4a6b-8c5d-1e2f3a4b5c6d", "description": "The ID of the credential." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"tenant_id\": \"acme-production\", \"credential_type_slug\": \"revenexx:smtp\", \"name\": \"Production SMTP\", \"status\": \"active\", \"public_config\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Update a credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4f2a-7d3e-4a6b-8c5d-1e2f3a4b5c6d", "description": "The ID of the credential." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Mailpit (staging)\",\"config\":{\"host\":\"smtp.example.com\",\"port\":587,\"username\":\"mailer\",\"password\":\"sekret\"}}" }, "description": "Updates the name and\/or `config`. When `config` is supplied it is\nre-validated against the credential type's declared fields." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"tenant_id\": \"acme-production\", \"credential_type_slug\": \"revenexx:smtp\", \"name\": \"Production SMTP\", \"status\": \"active\", \"public_config\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T11:00:00Z\"}", "name": "Updated" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The given data was invalid.\", \"errors\": {\"config\": [\"...\"]}}", "name": "Validation failed" } ] }, { "name": "Delete a credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4f2a-7d3e-4a6b-8c5d-1e2f3a4b5c6d", "description": "The ID of the credential." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Test a saved credential", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/:id\/test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/:id\/test", "variable": [ { "id": "id", "key": "id", "value": "9c1b4f2a-7d3e-4a6b-8c5d-1e2f3a4b5c6d", "description": "The ID of the credential." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Runs the credential type's connection test in the broker against the\nstored config and records the outcome on the instance (`last_test_at`,\n`last_test_ok`, `last_test_message`), so the answer to \"do these\ncredentials actually work?\" survives a reload \u2014 `status` cannot answer\nthat, it only tracks the OAuth refresh lifecycle. The stored config is\nnever modified." }, "response": [ { "header": [], "code": 200, "body": "{\"ok\": true, \"message\": null, \"last_test_at\": \"2026-07-16T21:00:00+00:00\", \"last_test_ok\": true}", "name": "Tested" } ] }, { "name": "Begin 3-legged OAuth setup", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/credentials\/:id\/oauth\/authorize-url", "query": [], "raw": "{{baseUrl}}\/api\/v1\/credentials\/:id\/oauth\/authorize-url", "variable": [ { "id": "id", "key": "id", "value": "9c1b4f2a-7d3e-4a6b-8c5d-1e2f3a4b5c6d", "description": "The ID of the credential." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the provider authorize URL for the credential. The caller (the\ncockpit) opens it; the provider redirects back to the public callback." }, "response": [ { "header": [], "code": 200, "body": "{\"authorize_url\": \"https:\/\/login.example.com\/authorize?client_id=...&state=...\"}", "name": "Authorize URL" }, { "header": [], "code": 422, "body": "{\"message\": \"Credential type does not use 3-legged OAuth.\"}", "name": "Not a 3-legged OAuth type" } ] } ] }, { "name": "Node Packages", "description": "", "item": [ { "name": "Stream a node-package image.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/node-packages\/images\/:id", "query": [ { "key": "expires", "value": "16", "description": "Signed-URL expiry (added by the signer).", "disabled": false }, { "key": "signature", "value": "architecto", "description": "URL signature (added by the signer).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/node-packages\/images\/:id?expires=16&signature=architecto", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the image." }, { "id": "image", "key": "image", "value": "9b2e6b1e-6d0a-5f3a-8c1b-2b7f6a1c9d4e", "description": "The image UUID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "\"\"", "name": "Valid signature" }, { "header": [], "code": 403, "body": "{\"message\": \"Invalid signature.\"}", "name": "Missing, tampered, or expired signature" }, { "header": [], "code": 404, "body": "{\"message\": \"Not Found\"}", "name": "Unknown image, or stored file missing" } ] } ] }, { "name": "Nodes", "description": "\nGlobally registered node definitions, addressed publicly by\n`\/`. Read endpoints additionally accept the alias\n`latest` in place of an explicit version. The `DELETE` endpoint refuses\nthe alias and requires an exact version, so the caller always knows which\nrow they're touching.\n\nNodes are created and updated exclusively through the node-package upload\n(`POST \/v1\/admin\/orgs\/{org_id}\/node-packages`), which extracts the manifests\nfrom the published tarball \u2014 there is no standalone create\/update endpoint,\nsince a node always ships with its runtime code.\n\nAuthentication is required for every endpoint, but the resource itself\nis *not* tenant-scoped \u2014 per-tenant entitlement (which tenant may use\nwhich node) is the responsibility of a future app-registration flow.", "item": [ { "name": "List nodes", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes", "query": [ { "key": "namespace", "value": "revenexx", "description": "Filter by the slug-derived namespace (e.g. `revenexx`).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/nodes?namespace=revenexx" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the registered nodes ordered by `slug` ascending, then\nsemver descending. Optionally filters to a single namespace via the\n`namespace` query parameter." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"name\": \"HTTP request\", \"namespace\": \"revenexx\", \"slug\": \"revenexx:http-request\", \"version\": \"1.0.0\", \"package\": {\"name\": \"@revenexx\/integrations-nodes-core\", \"version\": \"0.2.0\", \"label\": \"Core\"}, \"manifest_version\": \"v0-draft\", \"manifest\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "List versions for a node", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes\/:slug\/versions", "query": [], "raw": "{{baseUrl}}\/api\/v1\/nodes\/:slug\/versions", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Ahttp-request", "description": "Full node slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the registered versions for a given slug, semver-descending.\nThe slug must match at least one stored row, otherwise a 404 is\nreturned \u2014 there's no representation for \"an empty list of\nversions\". The response intentionally only contains version\nstrings; callers that need the full row should follow up with\n`GET \/nodes\/{slug}\/{version}`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [\"2.5.0\", \"1.10.0\", \"1.0.0\"]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Unknown slug" } ] }, { "name": "Show a node", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes\/:slug\/:version", "query": [], "raw": "{{baseUrl}}\/api\/v1\/nodes\/:slug\/:version", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Ahttp-request", "description": "Full node slug." }, { "id": "version", "key": "version", "value": "1.0.0", "description": "Semver, or the alias `latest`." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns a single node by `(slug, version)`. The version may be the\nliteral string `latest`, in which case the highest semver registered\nfor the slug is returned." }, "response": [ { "header": [], "code": 200, "body": "{\"name\": \"HTTP request\", \"namespace\": \"revenexx\", \"slug\": \"revenexx:http-request\", \"version\": \"1.0.0\", \"package\": {\"name\": \"@revenexx\/integrations-nodes-core\", \"version\": \"0.2.0\", \"label\": \"Core\"}, \"manifest_version\": \"v0-draft\", \"manifest\": {}, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Resolve dynamic node config", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes\/:slug\/:version\/config:resolve", "query": [], "raw": "{{baseUrl}}\/api\/v1\/nodes\/:slug\/:version\/config:resolve", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Aapi", "description": "Full node slug." }, { "id": "version", "key": "version", "value": "1.0.0", "description": "Semver, or the alias `latest`." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"target\":\"*\",\"config\":{\"customerId\":\"42\"},\"locale\":\"de\",\"search\":\"acme\"}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"fields\": [{\"key\": \"customerId\", \"type\": \"string\"}], \"outputs\": [{\"name\": \"success\"}]}", "name": "Resolved" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Unknown node" }, { "header": [], "code": 409, "body": "{\"message\": \"This node version has no built code, so it cannot be executed. Its code is built when its package is registered.\"}", "name": "Node version has no built code" }, { "header": [], "code": 502, "body": "{\"message\": \"Node runtime resolve failed: ...\"}", "name": "Node runtime unavailable or failed" } ] }, { "name": "Test-execute a node", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes\/:slug\/:version\/execute:test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/nodes\/:slug\/:version\/execute:test", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Aapi", "description": "Full node slug." }, { "id": "version", "key": "version", "value": "1.0.0", "description": "Semver, or the alias `latest`." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"config\":{\"customerId\":\"42\"},\"inputs\":{\"payload\":{\"email\":\"test@acme.com\"}},\"timeout_ms\":30000,\"workflow_id\":12}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"outputs\": {\"customer\": {\"id\": \"42\"}}, \"branch\": \"success\", \"logs\": [{\"level\": \"info\", \"message\": \"fetched customer 42\"}]}", "name": "Executed" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Unknown node" }, { "header": [], "code": 409, "body": "{\"message\": \"This node version has no built code, so it cannot be executed. Its code is built when its package is registered.\"}", "name": "Node version has no built code" }, { "header": [], "code": 422, "body": "{\"error\": {\"message\": \"rate limited\", \"code\": \"RATE_LIMITED\"}, \"logs\": []}", "name": "Node threw" }, { "header": [], "code": 502, "body": "{\"message\": \"Node runtime execute failed: ...\"}", "name": "Node runtime unavailable" } ] }, { "name": "Delete a node", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/nodes\/:slug\/:version", "query": [], "raw": "{{baseUrl}}\/api\/v1\/nodes\/:slug\/:version", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Ahttp-request", "description": "Full node slug." }, { "id": "version", "key": "version", "value": "1.0.0", "description": "Exact semver of the node version to delete; the alias `latest` is rejected." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Removes the node version identified by `(slug, version)`. The\n`latest` alias is rejected to prevent ambiguous deletes." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 400, "body": "{\"message\": \"The `latest` alias is not allowed for mutating requests.\"}", "name": "Latest alias rejected" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] } ] }, { "name": "Run Dead Letters", "description": "\nA trigger firing that could not start a run \u2014 and left no failed run row to\nretry \u2014 is captured here so it can be replayed once the cause is resolved\n(typically the workflow bundle finishing its build) or explicitly discarded.", "item": [ { "name": "List dead-lettered firings for a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/dead-letters", "query": [ { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Number of dead letters per page (1\u2013100). Defaults to 25. Must be at least 1. Must not be greater than 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/dead-letters?page=1&per_page=25", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Newest first. Only firings for the addressed workflow, scoped to the\nauthenticated tenant." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"total\": 0, \"last_page\": 1}}", "name": "Success" } ] }, { "name": "List the tenant's missed firings", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/dead-letters", "query": [ { "key": "status[0]", "value": "pending", "description": "Restrict to firings in these handling states. One value, or several comma-separated (pending, replayed, discarded).", "disabled": false }, { "key": "workflow_id", "value": "1", "description": "Restrict to firings of one workflow. A workflow of another tenant is rejected. Must be at least 1.", "disabled": false }, { "key": "since", "value": "2026-08-01T00%3A00%3A00Z", "description": "Only firings captured at or after this instant. Must be a valid date.", "disabled": false }, { "key": "until", "value": "2026-08-21T00%3A00%3A00Z", "description": "Only firings captured at or before this instant. Must not precede `since`. Must be a valid date. Must be a date after or equal to since.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Firings per page. Clamped to the configured maximum (100) rather than rejected.", "disabled": false }, { "key": "search", "value": "", "description": "", "disabled": true } ], "raw": "{{baseUrl}}\/api\/v1\/dead-letters?status[0]=pending&workflow_id=1&since=2026-08-01T00%3A00%3A00Z&until=2026-08-21T00%3A00%3A00Z&page=1&per_page=25&search=" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Every trigger firing across the tenant that never became a run, newest\nfirst. Optionally narrowed by handling state, by workflow and by a time\nwindow.\n\nThe sibling of `GET \/v1\/runs`: a firing that produced a run belongs\nthere, one that produced none belongs here. Each row names the workflow\nit belongs to, which the per-workflow list can leave to the request path\nand this one cannot.\n\nNo total is reported \u2014 `GET \/v1\/dead-letters\/summary` answers \"how many\",\nincluding the count of those still waiting." }, "response": [ { "header": [], "code": 0, "body": "{\"data\": [{\"id\": 7, \"workflow_id\": 1, \"workflow_name\": \"Sync orders\", \"trigger_id\": 3, \"source\": \"schedule\", \"trigger_handle\": \"9f1c8e2a-0b4d-4f7e-9a3c-1d2e3f4a5b6c\", \"reason\": \"Workflow bundle not ready (build_\", \"status\": \"pending\", \"created_at\": \"2026-08-21T02:00:00Z\", \"updated_at\": \"2026-08-21T02:00:00Z\"}], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"has_more\": false}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" }, { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "x-request-id", "value": "fc60e865-6f17-444f-b9c3-6dc8b49bae51" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 500, "body": "{\n \"message\": \"Server Error\"\n}", "name": "" } ] }, { "name": "Count the tenant's missed firings", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/dead-letters\/summary", "query": [ { "key": "status[0]", "value": "pending", "description": "Restrict to firings in these handling states. One value, or several comma-separated (pending, replayed, discarded).", "disabled": false }, { "key": "workflow_id", "value": "1", "description": "Restrict to firings of one workflow. A workflow of another tenant is rejected. Must be at least 1.", "disabled": false }, { "key": "since", "value": "2026-08-01T00%3A00%3A00Z", "description": "Only firings captured at or after this instant. Must be a valid date.", "disabled": false }, { "key": "until", "value": "2026-08-21T00%3A00%3A00Z", "description": "Only firings captured at or before this instant. Must not precede `since`. Must be a valid date. Must be a date after or equal to since.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Firings per page. Clamped to the configured maximum (100) rather than rejected.", "disabled": false }, { "key": "search", "value": "", "description": "", "disabled": true } ], "raw": "{{baseUrl}}\/api\/v1\/dead-letters\/summary?status[0]=pending&workflow_id=1&since=2026-08-01T00%3A00%3A00Z&until=2026-08-21T00%3A00%3A00Z&page=1&per_page=25&search=" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "How many firings never became runs, broken down by handling state, under\nexactly the narrowing `GET \/v1\/dead-letters` accepts.\n\n`by_status.pending` is the count the studio shows on its Missed runs tab\nand on the dashboard: the firings still waiting to be sent through or put\naside. Every state appears, zeros included, so \"none waiting\" cannot read\nas \"not loaded yet\"." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"total\": 7, \"by_status\": {\"pending\": 4, \"replayed\": 2, \"discarded\": 1}}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" } ] }, { "name": "Replay a dead-lettered firing", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/dead-letters\/:id\/replay", "query": [], "raw": "{{baseUrl}}\/api\/v1\/dead-letters\/:id\/replay", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The dead letter id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Starts a fresh run from the captured trigger payload + handle. Requires\nthe workflow to be runnable again; marks the dead letter `replayed`." }, "response": [ { "header": [], "code": 0, "body": "{\"message\": \"Workflow bundle is not ready (build_\"}", "name": "Workflow not runnable" }, { "header": [], "code": 202, "body": "{\"id\": 5, \"workflow_id\": 1, \"status\": \"running\"}", "name": "Accepted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Dead letter has already been replayed or discarded.\"}", "name": "Already handled" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow has no active manual trigger; pass trigger_handle to start a specific trigger.\"}", "name": "Trigger no longer resolvable" }, { "header": [], "code": 503, "body": "{\"message\": \"Workflow worker is unavailable.\"}", "name": "Worker unavailable" } ] }, { "name": "Discard a dead-lettered firing", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/dead-letters\/:id\/discard", "query": [], "raw": "{{baseUrl}}\/api\/v1\/dead-letters\/:id\/discard", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The dead letter id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Marks the dead letter `discarded` without starting a run." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"status\": \"discarded\"}", "name": "Discarded" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Dead letter has already been replayed or discarded.\"}", "name": "Already handled" } ] } ] }, { "name": "Runs", "description": "\nEvery run of every workflow the tenant owns, in one list the platform orders\nand pages itself. The studio's Runs page reads this; a workflow's own Runs tab\nreads the per-workflow subresource\n(`GET \/workflows\/{workflowId}\/runs`), whose contract is unchanged.\n\nIts own controller rather than more methods on\n{@see WorkflowRunController}: that class orchestrates starting, cancelling,\nresuming and inspecting a run and carries the services to do it. This is a\nread, and it needs none of them.", "item": [ { "name": "List the tenant's runs", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/runs", "query": [ { "key": "status[0]", "value": "failed", "description": "Restrict to runs in these statuses. One value, or several comma-separated (pending, running, completed, failed, cancelled, terminated).", "disabled": false }, { "key": "workflow_id", "value": "1", "description": "Restrict to runs of one workflow. A workflow of another tenant is rejected. Must be at least 1.", "disabled": false }, { "key": "since", "value": "2026-08-01T00%3A00%3A00Z", "description": "Only runs created at or after this instant. Must be a valid date.", "disabled": false }, { "key": "until", "value": "2026-08-21T00%3A00%3A00Z", "description": "Only runs created at or before this instant. Must not precede `since`. Must be a valid date. Must be a date after or equal to since.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Runs per page. Clamped to the configured maximum (100) rather than rejected.", "disabled": false }, { "key": "trigger_type", "value": "schedule", "description": "Restrict to runs started by this kind of trigger (manual, schedule, webhook, event).", "disabled": false }, { "key": "search", "value": "orders", "description": "optional Narrow to runs of workflows whose name contains this text (case-insensitive).", "disabled": false }, { "key": "sort", "value": "duration", "description": "Which order to read the list in (created_at, started_at, duration). Defaults to `created_at`. `duration` is the time between a run starting and finishing. A run the chosen column cannot describe \u2014 one that never started, or one still running \u2014 is listed last whichever direction is asked for. Ordering is always broken by the run id, so paging never repeats or loses a row.", "disabled": false }, { "key": "direction", "value": "desc", "description": "Which way to read the order: `desc` (the default) or `asc`.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/runs?status[0]=failed&workflow_id=1&since=2026-08-01T00%3A00%3A00Z&until=2026-08-21T00%3A00%3A00Z&page=1&per_page=25&trigger_type=schedule&search=orders&sort=duration&direction=desc" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Newest first, across every workflow the tenant owns, and optionally in\nanother order \u2014 by when a run started, or by how long it took. Optionally\nnarrowed by outcome, by the kind of trigger that\nstarted the run, by workflow, and by a time window; the filters narrow\ntogether, and the order applies to what they left.\n\nThe rows are leaner than the per-workflow list's: a run's `result` and\ncaptured trigger payload are not included, because they can run to\nmegabytes each. Read them from `GET \/workflows\/{workflowId}\/runs\/{runId}`.\n\nNo total is reported. `GET \/v1\/runs\/summary` answers \"how many\", and\nanswers it under the same narrowing \u2014 a page cannot, and pretending\notherwise is what made clients read every page to count." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 42, \"workflow_id\": 1, \"workflow_name\": \"Sync orders\", \"status\": \"failed\", \"error\": \"Node revenexx:http-request failed: 500\", \"trigger_handle\": \"9f1c8e2a-0b4d-4f7e-9a3c-1d2e3f4a5b6c\", \"trigger_type\": \"schedule\", \"temporal_workflow_id\": \"acme-production:1:42\", \"temporal_run_id\": \"018f...\", \"started_at\": \"2026-08-21T02:00:00Z\", \"completed_at\": \"2026-08-21T02:00:07Z\", \"created_at\": \"2026-08-21T02:00:00Z\", \"updated_at\": \"2026-08-21T02:00:07Z\"}], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"has_more\": false}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" }, { "header": [], "code": 422, "body": "{\"message\": \"The given data was invalid.\", \"errors\": {\"status.0\": [\"The selected status.0 is invalid.\"]}}", "name": "Unknown status" } ] }, { "name": "Count the tenant's runs", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/runs\/summary", "query": [ { "key": "status[0]", "value": "failed", "description": "Restrict to runs in these statuses. One value, or several comma-separated (pending, running, completed, failed, cancelled, terminated).", "disabled": false }, { "key": "workflow_id", "value": "1", "description": "Restrict to runs of one workflow. A workflow of another tenant is rejected. Must be at least 1.", "disabled": false }, { "key": "since", "value": "2026-08-01T00%3A00%3A00Z", "description": "Only runs created at or after this instant. Must be a valid date.", "disabled": false }, { "key": "until", "value": "2026-08-21T00%3A00%3A00Z", "description": "Only runs created at or before this instant. Must not precede `since`. Must be a valid date. Must be a date after or equal to since.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Runs per page. Clamped to the configured maximum (100) rather than rejected.", "disabled": false }, { "key": "trigger_type", "value": "schedule", "description": "Restrict to runs started by this kind of trigger (manual, schedule, webhook, event).", "disabled": false }, { "key": "search", "value": "orders", "description": "Restrict to runs whose workflow's name contains this text (case-insensitive). Must not be greater than 200 characters.", "disabled": false }, { "key": "sort", "value": "duration", "description": "Which order to read the list in (created_at, started_at, duration). Defaults to `created_at`. `duration` is the time between a run starting and finishing. A run the chosen column cannot describe \u2014 one that never started, or one still running \u2014 is listed last whichever direction is asked for. Ordering is always broken by the run id, so paging never repeats or loses a row.", "disabled": false }, { "key": "direction", "value": "desc", "description": "Which way to read the order: `desc` (the default) or `asc`.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/runs\/summary?status[0]=failed&workflow_id=1&since=2026-08-01T00%3A00%3A00Z&until=2026-08-21T00%3A00%3A00Z&page=1&per_page=25&trigger_type=schedule&search=orders&sort=duration&direction=desc" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "How many runs the tenant has, broken down by outcome, under exactly the\nnarrowing `GET \/v1\/runs` accepts \u2014 so a figure and the list beside it can\nnever disagree.\n\nSeparate from the list on purpose. Coupling \"how many\" to \"which page\" is\nwhat made clients read every page to count, and a tenant-wide COUNT on a\nlist that refreshes itself every few seconds is the most expensive query\nthis surface could ask for. Asked on its own, it can be asked less often.\n\nEvery status is present, zeros included. An absent key would leave \"none\nof those\" and \"not loaded\" reading alike, which is the confusion these\nfigures exist to remove." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"total\": 124, \"in_flight\": 3, \"by_status\": {\"pending\": 1, \"running\": 2, \"completed\": 100, \"failed\": 19, \"cancelled\": 1, \"terminated\": 1}}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" } ] }, { "name": "The latest run of each workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/runs\/latest-per-workflow", "query": [], "raw": "{{baseUrl}}\/api\/v1\/runs\/latest-per-workflow" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "One row per workflow that has ever run \u2014 its most recent run \u2014 newest\nworkflow first. Workflows that have never run are absent rather than\npresent-and-empty.\n\nIts own endpoint because it is a different question from the feed, not a\npage of it. `specs\/workflows.md` AC-4 promises a row says how its workflow\nlast ran, and that a workflow which never ran claims no outcome at all \u2014\nso reading it off the first page of the tenant's runs would make a\nworkflow whose last run happens to be older than a hundred others claim it\nhad never run, which is the mirror of the lie that criterion forbids.\n\nUnpaged: there is at most one row per workflow, the same bound\n`GET \/v1\/workflows` already lives with." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 42, \"workflow_id\": 1, \"workflow_name\": \"Sync orders\", \"status\": \"failed\", \"error\": \"Node revenexx:http-request failed: 500\", \"trigger_handle\": \"9f1c8e2a-0b4d-4f7e-9a3c-1d2e3f4a5b6c\", \"trigger_type\": \"schedule\", \"temporal_workflow_id\": \"acme-production:1:42\", \"temporal_run_id\": \"018f...\", \"started_at\": \"2026-08-21T02:00:00Z\", \"completed_at\": \"2026-08-21T02:00:07Z\", \"created_at\": \"2026-08-21T02:00:00Z\", \"updated_at\": \"2026-08-21T02:00:07Z\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" } ] } ] }, { "name": "Schedules", "description": "\nEvery scheduled trigger the tenant owns, on one list, each saying when it\nfires next and when it last really ran.\n\nThe per-workflow trigger list cannot answer this surface's questions: how many\nschedules are live across the tenant, and which timezones its schedules are\nactually in, are counts over the tenant rather than over one workflow \u2014 so a\nclient assembling them from a fan-out could only ever report what it had\nmanaged to load.", "item": [ { "name": "List the tenant's schedules", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/schedules", "query": [ { "key": "active", "value": "1", "description": "Restrict to live (`true`) or paused (`false`) schedules.", "disabled": false }, { "key": "timezone", "value": "Europe%2FBerlin", "description": "Restrict to schedules that run in this timezone. Matches the effective zone, so the platform default also matches schedules that carry none. The zones actually in use are reported as `meta.timezones`.", "disabled": false }, { "key": "next_fire_count", "value": "1", "description": "How many upcoming firings each schedule reports (1\u201310). Defaults to 1. Must be at least 1. Must not be greater than 10.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/schedules?active=1&timezone=Europe%2FBerlin&next_fire_count=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Every `schedule` trigger across every workflow, and nothing else \u2014 a\nwebhook or a manual trigger is not a schedule and is not listed.\n\nServed whole rather than paged, like the tenant's workflows and\ncredentials: there is one row per schedule, the page that shows them\nnarrows and sorts them in the browser, and a count of what is live is only\ntrue if it covers all of them. `meta` therefore describes the whole\ntenant, not a page." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 13, \"workflow_id\": 1, \"workflow_name\": \"Sync orders\", \"handle\": \"9f1c8e2a-0b4d-4f7e-9a3c-1d2e3f4a5b6c\", \"name\": null, \"active\": true, \"workflow_active\": true, \"schedule\": {\"cron\": \"0 3 * * *\", \"timezone\": \"Europe\/Berlin\", \"timezone_source\": \"schedule\", \"holds_firings\": true, \"not_firing_reason\": null, \"next_fire_at\": \"2026-08-22T01:00:00Z\", \"next_fire_times\": [{\"at\": \"2026-08-22T01:00:00Z\", \"local\": \"2026-08-22T03:00:00+02:00\"}], \"last_dispatch_at\": \"2026-08-21T01:00:00Z\", \"last_run\": {\"id\": 4711, \"status\": \"completed\", \"error\": null, \"started_at\": \"2026-08-21T01:00:01Z\", \"completed_at\": \"2026-08-21T01:00:44Z\"}}, \"created_at\": \"2026-06-15T10:00:00Z\", \"updated_at\": \"2026-06-15T10:00:00Z\"}], \"meta\": {\"total\": 1, \"live_count\": 1, \"timezones\": [\"Europe\/Berlin\"]}}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Tenant context is required.\"}", "name": "No tenant context" } ] } ] }, { "name": "Schemas", "description": "\nPublic, read-only access to the JSON-Schema definitions used to validate\nversioned payloads (currently the workflow `blob` and the node manifest).\nSchemas are global \u2014 they describe the shape of payloads regardless of\ntenant \u2014 so these endpoints are intentionally unauthenticated.", "item": [ { "name": "List schema versions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/schemas\/:domain", "query": [], "raw": "{{baseUrl}}\/api\/v1\/schemas\/:domain", "variable": [ { "id": "domain", "key": "domain", "value": "workflow", "description": "The schema domain. Supported domains: `workflow`, `node`." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the identifiers of every registered schema version for the given\ndomain, in registration order (which is also the order in which they\nare accepted by the validation layer).", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"domain\": \"workflow\", \"versions\": [\"v0-draft\"]}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Unknown schema domain.\"}", "name": "Unknown domain" } ] }, { "name": "Show a schema version", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/schemas\/:domain\/:version", "query": [], "raw": "{{baseUrl}}\/api\/v1\/schemas\/:domain\/:version", "variable": [ { "id": "domain", "key": "domain", "value": "workflow", "description": "The schema domain." }, { "id": "version", "key": "version", "value": "v0-draft", "description": "The schema version identifier." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the serialized JSON-Schema definition for one specific\n`(domain, version)` pair. The payload uses the standard JSON Schema\nvocabulary (`type`, `properties`, `required`, \u2026) and is suitable for\nclient-side validation or form generation.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"domain\": \"workflow\", \"version\": \"v0-draft\", \"schema\": {\"title\": \"Workflow Definition (v0-draft)\", \"type\": \"object\"}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Unknown schema version.\"}", "name": "Unknown version" } ] } ] }, { "name": "State Store", "description": "\nThe operator's window into the tenant state store (PO-374): which namespaces\nexist, what they hold, and the ability to correct a single entry when a sync\nwent wrong.\n\nThis exists because the support question is never abstract \u2014 it is \"why was\narticle X created twice?\", and the answer is one lookup away if somebody can\nsee the correlation and the run that wrote it. Without this view the store\nwould be a black box that only the workflow author can reason about.\n\nDeliberately read-and-correct, not read-and-write: there is no bulk import.\nThat is the door through which \"let's just load our master data in here\"\nwalks in, and the store is not a database.", "item": [ { "name": "List state namespaces", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/state\/namespaces", "query": [], "raw": "{{baseUrl}}\/api\/v1\/state\/namespaces" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Every namespace in the current tenant, with its entry count." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 1, \"name\": \"article\", \"role\": \"mapping\", \"visibility\": \"shared\", \"owner_workflow_id\": null, \"entries\": 2, \"ttl_seconds\": null, \"updated_at\": \"2026-08-26T10:00:00Z\"}]}", "name": "Success" } ] }, { "name": "List the entries of a namespace", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/state\/namespaces\/:id\/entries", "query": [ { "key": "q", "value": "pim%3A12345", "description": "Narrow to entries whose key contains this.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/state\/namespaces\/:id\/entries?q=pim%3A12345", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The namespace id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"q\":\"b\",\"per_page\":22}" }, "description": "Paginated, narrowable by key with `?q=`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 7, \"key\": \"pim:12345\", \"value\": \"erp:A-8891\", \"last_run_id\": 42, \"updated_at\": \"2026-08-26T10:00:00Z\"}], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"total\": 1, \"last_page\": 1}}", "name": "Success" } ] }, { "name": "Delete one entry", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/state\/namespaces\/:id\/entries\/:entryId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/state\/namespaces\/:id\/entries\/:entryId", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The namespace id." }, { "id": "entryId", "key": "entryId", "value": "7", "description": "The entry id." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "The correction path for a wrong correlation or a stuck cursor. Audited,\nbecause an operator editing what a run wrote is exactly the kind of\nchange somebody will want to trace back later." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" } ] }, { "name": "Delete a namespace", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/state\/namespaces\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/state\/namespaces\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The namespace id." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Removes the namespace and every entry in it. The explicit act a shared\nnamespace requires: it outlives the workflows that declared it, so\nnothing else ever removes one." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" } ] } ] }, { "name": "Templates", "description": "\nCatalogue of the workflow templates registered via node packages, plus the\n\"install\" actions a UI uses to turn one into a real workflow. Listing\/showing\nis global; instantiation is scoped to the current tenant.", "item": [ { "name": "List templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the latest registered version of each template, without the\n(heavy) embedded workflow `definition` blob \u2014 that ships only on `show`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"slug\": \"revenexx:bc-sales-order-digest\", \"version\": \"1.0.0\", \"category\": \"sales\", \"level\": \"beginner\", \"name\": \"Daily Sales-Order Digest\", \"shortDescription\": \"Email a daily summary of Business Central sales orders.\", \"description\": null, \"icon\": \"mdi:email-newsletter\", \"industries\": [\"any\"], \"vendors\": [\"microsoft\", \"business-central\"], \"images\": [{\"src\": \"https:\/\/api.example.com\/v1\/node-packages\/images\/2b1c0000-0000-4000-8000-000000000000?expires=1750000000&signature=abcdef\", \"alt\": {\"en\": \"Business Central banner\"}, \"title\": {\"en\": \"Business Central\"}, \"category\": \"banner\"}], \"triggerTypes\": [\"schedule\"]}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Show a template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Aslack-to-crm", "description": "Namespaced template slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the latest registered version of the template identified by its\nnamespaced slug, including the embedded workflow `definition` used to\ninstantiate a new workflow." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"slug\": \"revenexx:bc-sales-order-digest\", \"version\": \"1.0.0\", \"category\": \"sales\", \"level\": \"beginner\", \"name\": \"Daily Sales-Order Digest\", \"shortDescription\": \"Email a daily summary of Business Central sales orders.\", \"description\": null, \"icon\": \"mdi:email-newsletter\", \"industries\": [\"any\"], \"vendors\": [\"microsoft\", \"business-central\"], \"images\": [{\"src\": \"https:\/\/api.example.com\/v1\/node-packages\/images\/2b1c0000-0000-4000-8000-000000000000?expires=1750000000&signature=abcdef\", \"alt\": {\"en\": \"Business Central banner\"}, \"title\": {\"en\": \"Business Central\"}, \"category\": \"banner\"}], \"triggerTypes\": [\"schedule\"], \"blob_version\": \"v0-draft\", \"definition\": {\"nodeManifestVersion\": \"v0-draft\", \"name\": \"Daily Sales-Order Digest\", \"nodes\": [], \"edges\": []}, \"triggers\": [{\"handle\": \"a1c0ffee-0001-4001-8001-000000000001\", \"type\": \"schedule\", \"config\": {\"cron\": \"0 7 * * *\"}}]}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Template installation requirements", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:slug\/requirements", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:slug\/requirements", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Aslack-to-crm", "description": "Namespaced template slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Lists the credential types and secret keys the template's workflow\nreferences, cross-referenced against the current tenant (how many\ncredential instances already exist, whether each secret key is stored) so\nan install UI can have the user provision what is missing first." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"credentialTypes\": [{\"slug\": \"revenexx:business-central\", \"registered\": true, \"existingInstances\": 1, \"usedBy\": [{\"nodeId\": \"list_orders\", \"configKey\": \"credentials\"}], \"version\": \"1.0.0\", \"name\": \"Business Central\", \"authKind\": \"oauth2-client-credentials\", \"fields\": []}], \"secrets\": []}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Instantiate a template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/templates\/:slug\/instantiate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/templates\/:slug\/instantiate", "variable": [ { "id": "slug", "key": "slug", "value": "revenexx%3Aslack-to-crm", "description": "Namespaced template slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"name\":\"My Slack flow\",\"credential_bindings\":[[\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\"]]}" }, "description": "Creates a new workflow (and its triggers) for the current tenant from the\ntemplate's blueprint. Trigger handles are regenerated so repeated installs\nnever collide; the workflow and all triggers start inactive. Returns the\ncreated workflow." }, "response": [ { "header": [], "code": 201, "body": "{\"id\": 1, \"name\": \"Daily Sales-Order Digest\", \"description\": null, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"active\": false, \"revision\": 1, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Created" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The given data was invalid.\", \"errors\": {\"credential_bindings\": [\"The credential_bindings field must be an array.\"]}}", "name": "Validation failed" } ] } ] }, { "name": "Tenant Secrets", "description": "\nPer-tenant encrypted key\/value store. Values are AES-256-GCM encrypted at\nrest using a dedicated SECRETS_ENCRYPTION_KEY (separate from APP_KEY) and\nare never returned by the API.", "item": [ { "name": "List secrets", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/secrets", "query": [], "raw": "{{baseUrl}}\/api\/v1\/secrets" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the alphabetically sorted secrets of the current tenant in `data` \u2014\nkey plus timestamps, never the value. `updated_at` is when the value was\nlast written, which is what \"when was this last rotated\" asks for;\noverwriting a secret with the same plaintext still counts as a write.\n\nReplaces the earlier `{\"keys\": [...]}` envelope. Every consumer of this\nendpoint is first-party and reads `data`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"key\": \"SLACK_WEBHOOK_URL\", \"created_at\": \"2026-05-04T08:50:00.000000Z\", \"updated_at\": \"2026-05-04T08:50:00.000000Z\"}, {\"key\": \"STRIPE_API_KEY\", \"created_at\": \"2026-05-05T08:50:00.000000Z\", \"updated_at\": \"2026-07-01T11:02:00.000000Z\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Create or update a secret", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/secrets", "query": [], "raw": "{{baseUrl}}\/api\/v1\/secrets" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"key\":\"STRIPE_API_KEY\",\"value\":\"sk_live_abc123\"}" }, "description": "Upserts a secret value for the given key within the current tenant.\nReturns 201 on creation, 200 on update. The value is never echoed back." }, "response": [ { "header": [], "code": 200, "body": "{\"key\": \"STRIPE_API_KEY\", \"created_at\": \"2026-05-04T08:50:00Z\", \"updated_at\": \"2026-05-05T08:50:00Z\"}", "name": "Updated" }, { "header": [], "code": 201, "body": "{\"key\": \"STRIPE_API_KEY\", \"created_at\": \"2026-05-05T08:50:00Z\", \"updated_at\": \"2026-05-05T08:50:00Z\"}", "name": "Created" }, { "header": [], "code": 422, "body": "{\"message\": \"The key field format is invalid.\", \"errors\": {\"key\": [\"...\"]}}", "name": "Validation failed" } ] }, { "name": "Update a secret value", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/secrets\/:key", "query": [], "raw": "{{baseUrl}}\/api\/v1\/secrets\/:key", "variable": [ { "id": "key", "key": "key", "value": "bc-client-secret", "description": "The secret key to update." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"value\":\"sk_live_new_value\"}" }, "description": "Replaces the value of an existing secret. The key is immutable \u2014 create\na new secret and delete the old one if you need to rename a key. Returns\n404 if the key does not exist for the current tenant." }, "response": [ { "header": [], "code": 200, "body": "{\"key\": \"bc-client-secret\", \"created_at\": \"2026-05-04T08:50:00Z\", \"updated_at\": \"2026-06-12T10:00:00Z\"}", "name": "Updated" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The value field is required.\", \"errors\": {\"value\": [\"...\"]}}", "name": "Validation failed" } ] }, { "name": "Delete a secret", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/secrets\/:key", "query": [], "raw": "{{baseUrl}}\/api\/v1\/secrets\/:key", "variable": [ { "id": "key", "key": "key", "value": "STRIPE_API_KEY", "description": "The secret key to delete." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Removes the secret identified by `{key}` for the current tenant. The\nlookup is explicitly scoped to the current tenant, so a key belonging\nto another tenant \u2014 or one that does not exist at all \u2014 yields a 404\nwithout leaking existence either way." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] } ] }, { "name": "Triggers", "description": "\nManage triggers for a workflow. Triggers are the entry points that can start\na workflow execution (manual, schedule, webhook, or event). They live as DB entities\nrather than inside the workflow blob, and are referenced in blob edges via\ntheir stable UUID handle.", "item": [ { "name": "List triggers for a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/triggers", "query": [ { "key": "next_fire_count", "value": "3", "description": "optional How many upcoming firings each schedule reports (1\u201310). Defaults to 1.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/triggers?next_fire_count=3", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 12, \"workflow_id\": 1, \"handle\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\", \"type\": \"webhook\", \"name\": \"PSP webhook\", \"config\": {\"method\": \"POST\", \"public\": true, \"inbound\": {\"endpoint_id\": \"inb_abc123\", \"url\": \"https:\/\/webhooks.revenexx.com\/in\/inb_abc123\"}}, \"active\": true, \"created_at\": \"2026-06-15T10:00:00Z\", \"updated_at\": \"2026-06-15T10:00:00Z\"}]}", "name": "Success" }, { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 13, \"workflow_id\": 1, \"handle\": \"9f1c8e2a-0b4d-4f7e-9a3c-1d2e3f4a5b6c\", \"type\": \"schedule\", \"name\": null, \"config\": {\"cron\": \"0 3 * * *\", \"timezone\": \"Europe\/Berlin\"}, \"active\": true, \"schedule\": {\"cron\": \"0 3 * * *\", \"timezone\": \"Europe\/Berlin\", \"timezone_source\": \"schedule\", \"holds_firings\": true, \"not_firing_reason\": null, \"next_fire_at\": \"2026-08-22T01:00:00Z\", \"next_fire_times\": [{\"at\": \"2026-08-22T01:00:00Z\", \"local\": \"2026-08-22T03:00:00+02:00\"}], \"last_dispatch_at\": \"2026-08-21T01:00:00Z\", \"last_run\": {\"id\": 4711, \"status\": \"completed\", \"error\": null, \"started_at\": \"2026-08-21T01:00:01Z\", \"completed_at\": \"2026-08-21T01:00:44Z\"}}, \"created_at\": \"2026-06-15T10:00:00Z\", \"updated_at\": \"2026-06-15T10:00:00Z\"}]}", "name": "A schedule trigger" } ] }, { "name": "Create a trigger", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/triggers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/triggers", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"handle\":\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",\"type\":\"webhook\",\"name\":\"PSP webhook\",\"active\":true,\"config\":{\"method\":\"POST\",\"public\":true,\"authProfile\":\"token\"}}" }, "description": "" }, "response": [ { "header": [], "code": 201, "body": "{\"id\": 12, \"workflow_id\": 1, \"handle\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\", \"type\": \"webhook\", \"name\": \"PSP webhook\", \"config\": {\"method\": \"POST\", \"public\": true, \"inbound\": {\"endpoint_id\": \"inb_abc123\", \"url\": \"https:\/\/webhooks.revenexx.com\/in\/inb_abc123\"}}, \"active\": true, \"created_at\": \"2026-06-15T10:00:00Z\", \"updated_at\": \"2026-06-15T10:00:00Z\", \"inbound_secret\": \"whsec_ing_onetime\"}", "name": "Public webhook trigger" }, { "header": [], "code": 422, "body": "{\"message\": \"The config.method field is required.\", \"errors\": {\"config.method\": [\"The config.method field is required.\"]}}", "name": "Validation failed" } ] }, { "name": "Update a trigger", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/triggers\/:triggerId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/triggers\/:triggerId", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "triggerId", "key": "triggerId", "value": "1", "description": "The trigger id." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"type\":\"webhook\",\"name\":\"PSP webhook\",\"active\":true,\"config\":{\"method\":\"POST\",\"public\":true,\"authProfile\":\"token\"}}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 12, \"workflow_id\": 1, \"handle\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\", \"type\": \"webhook\", \"name\": \"PSP webhook\", \"config\": {\"method\": \"POST\", \"public\": true, \"inbound\": {\"endpoint_id\": \"inb_abc123\", \"url\": \"https:\/\/webhooks.revenexx.com\/in\/inb_abc123\"}}, \"active\": true, \"created_at\": \"2026-06-15T10:00:00Z\", \"updated_at\": \"2026-06-15T10:05:00Z\", \"inbound_secret\": \"whsec_ing_onetime\"}", "name": "Public webhook trigger" }, { "header": [], "code": 422, "body": "{\"message\": \"The config.method field is required.\", \"errors\": {\"config.method\": [\"The config.method field is required.\"]}}", "name": "Validation failed" } ] }, { "name": "Delete a trigger", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/triggers\/:triggerId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/triggers\/:triggerId", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "triggerId", "key": "triggerId", "value": "1", "description": "The trigger id." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" } ] }, { "name": "Rotate the ingest secret of a public webhook trigger", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/triggers\/:triggerHandle\/rotate-secret", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/triggers\/:triggerHandle\/rotate-secret", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "triggerHandle", "key": "triggerHandle", "value": "6ff8f7f6-1eb3-3525-be4a-3932c805afed", "description": "The trigger's UUID handle." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Generates a fresh ingest secret on the trigger's ingress endpoint. The\nprevious secret stops working immediately. Only available for webhook\ntriggers that are exposed via the inbound ingress (`config.public`)." }, "response": [ { "header": [], "code": 200, "body": "{\"inbound_secret\": \"whsec_ing_onetime\"}", "name": "Rotated" }, { "header": [], "code": 409, "body": "{\"message\": \"Trigger is not exposed via the inbound ingress; set config.public first.\"}", "name": "Not exposed" }, { "header": [], "code": 409, "body": "{\"message\": \"Secret rotation is not available: the inbound ingress is not configured.\"}", "name": "Ingress unavailable" } ] } ] }, { "name": "Webhooks", "description": "\nInbound endpoint that fires a workflow run for a webhook trigger. The\ntrigger is addressed by its UUID handle in the URL; authentication is the\nstandard JWT + `X-Tenant-Id` used by the rest of the API, so the trigger is\nresolved within the caller's tenant. The HTTP request (body, query,\nheaders, method) is delivered to the workflow as the trigger payload,\nreachable via `${{ trigger.payload.* }}`.", "item": [ { "name": "Fire a webhook trigger", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:handle", "query": [ { "key": "mode", "value": "async", "description": "optional Force `sync` or `async`. Honored for `caller_decides` workflows; conflicting with `async_only`\/`sync_only` yields 422.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:handle?mode=async", "variable": [ { "id": "handle", "key": "handle", "value": "0190a9c0-1111-7000-8000-000000000000", "description": "The webhook trigger handle (UUID)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Resolves the webhook trigger by handle, enforces the configured HTTP\nmethod, and starts a run. The mode follows the workflow's `execution_mode`\n(`async_only` \u2192 202; `sync_only`\/`caller_decides` \u2192 wait and return the\nresult), and can be overridden per request with `?mode=sync|async` when\nthe policy allows it \u2014 a conflicting `mode` is rejected with 422." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"completed\", \"result\": {}}", "name": "Completed (sync)" }, { "header": [], "code": 202, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"running\"}", "name": "Accepted (async)" }, { "header": [], "code": 404, "body": "{\"message\": \"No active webhook trigger with handle \u2026 exists.\"}", "name": "No such webhook trigger" }, { "header": [], "code": 405, "body": "{\"message\": \"This webhook expects POST.\"}", "name": "Method not allowed" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow does not allow sync execution (execution_mode=async_only).\"}", "name": "Mode conflicts with policy" } ] } ] }, { "name": "Workflow Credentials", "description": "\nRead-only introspection of which typed credentials a workflow's nodes\nreference through their `credentials-ref` config fields. Useful for pre-run\nchecks, access auditing, and impact analysis when a credential instance is\nrotated or deleted. The credential *values* are never touched here \u2014 only\nthe instance UUIDs and their credential type slugs are reported.", "item": [ { "name": "List credential ids used across the tenant's workflows", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/used-credentials", "query": [ { "key": "type", "value": "revenexx%3Asmtp", "description": "Filter to a single credential type slug.", "disabled": false }, { "key": "active", "value": "1", "description": "Only consider active workflows.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/used-credentials?type=revenexx%3Asmtp&active=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the distinct credential *instance* UUIDs referenced by every\nworkflow of the current tenant. Optionally filtered to a single\ncredential type slug via `?type={slug}` and\/or to active workflows only\nvia `?active=true`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [\"9f3e2c1a-0000-4000-8000-000000000001\", \"1ab2c3d4-0000-4000-8000-000000000002\"]}", "name": "Used credentials" } ] }, { "name": "List credential type slugs used across the tenant's workflows", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/used-credential-types", "query": [ { "key": "active", "value": "1", "description": "Only consider active workflows.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/used-credential-types?active=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the distinct credential *type* slugs (e.g. `revenexx:smtp`)\nreferenced by every workflow of the current tenant. Optionally filtered\nto active workflows only via `?active=true`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [\"revenexx:smtp\", \"revenexx:deepl\"]}", "name": "Used credential types" } ] }, { "name": "List credential ids used by a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/credentials", "query": [ { "key": "type", "value": "revenexx%3Asmtp", "description": "Filter to a single credential type slug.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/credentials?type=revenexx%3Asmtp", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the distinct credential *instance* UUIDs the workflow's nodes\nreference, optionally filtered to a single credential type slug via\n`?type={slug}`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [\"9f3e2c1a-0000-4000-8000-000000000001\", \"1ab2c3d4-0000-4000-8000-000000000002\"]}", "name": "Used credentials" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Workflow not found" } ] }, { "name": "List credential type slugs used by a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/credential-types", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/credential-types", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the distinct credential *type* slugs (e.g. `revenexx:smtp`) the\nworkflow's nodes reference through their `credentials-ref` config fields." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [\"revenexx:smtp\", \"revenexx:deepl\"]}", "name": "Used credential types" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Workflow not found" } ] } ] }, { "name": "Workflow Revisions", "description": "\nRead the archived revision history of a workflow and restore an old\nrevision. Every blob change to a workflow snapshots the previous revision\ninto `workflow_histories`; these endpoints expose that history and let a\nclient re-apply an old revision as a brand-new one.\n\nAll endpoints are scoped to the tenant resolved by the `resolve.tenant`\nmiddleware. Cross-tenant access returns 404 so the API never leaks the\nexistence of resources owned by other tenants.", "item": [ { "name": "List workflow revisions", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/revisions", "query": [ { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Number of revisions per page (1\u2013100). Defaults to 25. Must be at least 1. Must not be greater than 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/revisions?page=1&per_page=25", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the archived revisions of a workflow, newest first, paginated.\nList items carry metadata only \u2014 use the show endpoint to fetch a\nsingle revision's full `blob` and `triggers`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 7, \"revision\": 2, \"name\": \"Sync orders\", \"description\": null, \"active\": true, \"blob_definition_version\": \"v0-draft\", \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T11:00:00Z\", \"archived_at\": \"2026-05-06T12:00:00Z\"}], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"total\": 1, \"last_page\": 1}}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Workflow not found" } ] }, { "name": "Show a workflow revision", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/revisions\/:revision", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/revisions\/:revision", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "revision", "key": "revision", "value": "1", "description": "The archived revision number." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns a single archived revision in full, including its `blob` and\n`triggers` snapshot." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 7, \"revision\": 1, \"name\": \"Sync orders\", \"description\": null, \"active\": true, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"triggers\": [], \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T11:00:00Z\", \"archived_at\": \"2026-05-06T12:00:00Z\"}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Revision or workflow not found" } ] }, { "name": "Restore a workflow revision", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/revisions\/:revision\/restore", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/revisions\/:revision\/restore", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "revision", "key": "revision", "value": "1", "description": "The archived revision number to restore." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Re-applies the given archived revision's definition (`blob`,\n`blob_definition_version`, and `triggers`) to the workflow as a brand-new\nrevision. The current state is first snapshotted into the history, the\n`revision` counter is bumped, and a fresh bundle build is dispatched. The\nworkflow's `name`, `description` and `execution_mode` are left unchanged.\n`active` is preserved too, except that restoring a schema- or\nmanifest-invalid revision onto an active workflow forces it inactive to\nkeep the `active \u21d2 valid` invariant (PO-186) \u2014 the restore still succeeds.\n\nRestoring a revision whose definition is identical to the current one is\na safe no-op for the `revision` counter (no new history row is written),\nthough triggers are still re-synced from the snapshot." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"name\": \"Sync orders\", \"revision\": 3, \"build_status\": \"pending\", \"blob\": {}, \"triggers\": []}", "name": "Restored" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Revision or workflow not found" } ] } ] }, { "name": "Workflow Runs", "description": "\nTrigger and inspect executions of a workflow. Each run is handed off to\nthe workflow's dedicated Temporal worker, which orchestrates node\nexecution and streams status back.", "item": [ { "name": "List runs for a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs", "query": [ { "key": "page", "value": "1", "description": "Page number to retrieve (1-based). Defaults to 1. Must be at least 1.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Number of runs per page (1\u2013100). Defaults to 25. Must be at least 1. Must not be greater than 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs?page=1&per_page=25", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns all runs for the workflow, newest first." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [], \"meta\": {\"current_page\": 1, \"per_page\": 25, \"total\": 0, \"last_page\": 1}}", "name": "Success" } ] }, { "name": "Start a workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"trigger_payload\":{\"source\":\"api\"},\"trigger_handle\":\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",\"mode\":\"sync\"}" }, "description": "Execution behavior depends on workflow `execution_mode` and optional\nrequest `mode`:\n\n- Async: starts the run and returns HTTP 202 with status `running`.\n- Sync: waits for worker completion and returns HTTP 200\/422\/504\/503\n with the final outcome.\n\nFor `caller_decides`, omitting `mode` defaults to async execution." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"completed\", \"result\": {\"node-1\": {\"ok\": true}}, \"completed_at\": \"2026-05-22T10:00:30Z\"}", "name": "Sync completed" }, { "header": [], "code": 202, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"running\", \"temporal_workflow_id\": \"tenant:1:abc\", \"started_at\": \"2026-05-13T10:00:00Z\"}", "name": "Accepted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Workflow not found" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow configuration has unresolved issues and cannot run. Fix the reported fields and try again.\", \"errors\": {\"blob.nodes.0.config.credentials\": [\"Required config field 'credentials' is missing.\"]}}", "name": "Unresolved manifest issues (PO-186)" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow does not allow sync execution (execution_mode=async_only).\"}", "name": "Mode not allowed" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow execution failed.\", \"error\": \"node execution failed\", \"run\": {\"id\": 1, \"status\": \"failed\"}}", "name": "Sync failed" }, { "header": [], "code": 501, "body": "{\"message\": \"Synchronous workflow execution is not supported by the configured run starter driver.\"}", "name": "Sync not supported by starter" }, { "header": [], "code": 503, "body": "{\"message\": \"Workflow worker is unavailable.\"}", "name": "Worker unavailable" }, { "header": [], "code": 504, "body": "{\"message\": \"Workflow execution timed out.\", \"error\": \"Sync run for workflow 1 exceeded timeout of 30 seconds.\"}", "name": "Sync timeout" } ] }, { "name": "Get a workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the current state of a workflow run. If the run is still\nin progress, the worker is polled for the latest Temporal status." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"completed\", \"result\": {}, \"completed_at\": \"2026-05-13T10:01:00Z\"}", "name": "Completed" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Get execution details for a workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/details", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/details", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the execution description (status, timing, history length,\nparent linkage) via {@see WorkflowExecutionInspector}. The inspector\ntransparently routes between a live Temporal call and the local\nsnapshot taken when the run reached a terminal status; the response\ncarries a `source` field of `\"temporal\"` or `\"snapshot\"` so clients\nknow which view they are seeing." }, "response": [ { "header": [], "code": 200, "body": "{\"source\": \"temporal\", \"data\": {\"workflow_id\": \"tenant:1:abc\", \"run_id\": \"0190...\", \"status\": \"running\"}}", "name": "Live" }, { "header": [], "code": 200, "body": "{\"source\": \"snapshot\", \"data\": {\"workflow_id\": \"tenant:1:abc\", \"run_id\": \"0190...\", \"status\": \"completed\"}}", "name": "Snapshot" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run has no Temporal execution yet.\"}", "name": "Run not handed off to Temporal yet" }, { "header": [], "code": 410, "body": "{\"message\": \"Workflow execution history is no longer available.\"}", "name": "History unavailable" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Get execution history for a workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/history", "query": [ { "key": "page_token", "value": "", "description": "Opaque continuation token returned by the previous page. Omit for the first page. Must not be greater than 8192 characters.", "disabled": true }, { "key": "page_size", "value": "200", "description": "Maximum number of history events per page (1\u20131000). Defaults to the server-configured value. Must be at least 1. Must not be greater than 1000.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/history?page_token=&page_size=200", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns one page of history events via {@see WorkflowExecutionInspector}.\nLike the details endpoint, the response is hybrid-routed and carries\na `source` field. The `next_page_token` is opaque (source-tagged with\n`tmp:` or `snp:`); pass it verbatim to the next call. Note that\nswitching sources mid-pagination resets to page 1 (the response's\n`source` will change), which the client should treat as a fresh\npagination." }, "response": [ { "header": [], "code": 200, "body": "{\"source\": \"temporal\", \"data\": [{\"event_id\": 1, \"event_type\": \"workflow_execution_started\"}], \"next_page_token\": null}", "name": "Live page" }, { "header": [], "code": 200, "body": "{\"source\": \"snapshot\", \"data\": [{\"event_id\": 1}], \"next_page_token\": null}", "name": "Snapshot page" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run has no Temporal execution yet.\"}", "name": "Run not handed off to Temporal yet" }, { "header": [], "code": 410, "body": "{\"message\": \"Workflow execution history is no longer available.\"}", "name": "History unavailable" }, { "header": [], "code": 422, "body": "{\"message\": \"Invalid page_token.\"}", "name": "Invalid page token" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Get the per-node steps of a workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/steps", "query": [ { "key": "include_payloads", "value": "1", "description": "Whether to decode and include each step's input\/config\/output payloads. Defaults to true.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/steps?include_payloads=1", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Projects the run's flat Temporal history into an ordered list of node\nexecutions (one per scheduling, so a looped node yields one step per\niteration) for the step-through replay inspector: per node the status,\ntiming, duration, decoded input\/config\/output and any error. Like the\nhistory endpoint the response is hybrid-routed and carries a `source`\nfield (`snapshot` for terminal snapshotted runs, `temporal` for live\nreads). Node ids match the workflow blob's canvas node ids.\n\nA failed step's `error` carries the failure's `code` (as `type`) and a\nbounded `message`, and never a stack trace. Where the failure came from\na node's own code it also carries `frames`: the author's file relative\nto the package it belongs to, a 1-based line and column, and the\nfunction name where one was recorded, innermost first. Only frames\ninside a node package appear. `frames` is absent where the failure\nproduced none, or where the artifact the run executed has no source map\nstored \u2014 which is the case for every run recorded before this existed." }, "response": [ { "header": [], "code": 200, "body": "{\"source\": \"snapshot\", \"run\": {\"status\": \"completed\", \"started_at\": \"2026-05-22T10:00:00Z\", \"completed_at\": \"2026-05-22T10:00:05Z\"}, \"steps\": [{\"node_id\": \"node-1\", \"node_slug\": \"revenexx:http-request\", \"activity_type\": \"executeNode\", \"status\": \"completed\", \"attempt\": 0, \"scheduled_event_id\": 5, \"duration_ms\": 812, \"input\": {}, \"output\": {}, \"branch\": null, \"error\": null}]}", "name": "Projected steps" }, { "header": [], "code": 200, "body": "{\"source\": \"snapshot\", \"run\": {\"status\": \"failed\"}, \"steps\": [{\"node_id\": \"f-empty-text\", \"node_slug\": \"revenexx:deepl-translate\", \"activity_type\": \"executeNode\", \"status\": \"failed\", \"attempt\": 0, \"scheduled_event_id\": 5, \"duration_ms\": 41, \"input\": {}, \"output\": null, \"branch\": null, \"error\": {\"message\": \"No text found to translate\", \"type\": \"MISSING_TEXT\", \"frames\": [{\"file\": \"@revenexx\/integrations-nodes-core\/src\/nodes\/DeeplTranslateNode.ts\", \"line\": 5, \"column\": 11, \"name\": \"requireText\"}]}}]}", "name": "A step that failed inside a node" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run has no Temporal execution yet.\"}", "name": "Run not handed off to Temporal yet" }, { "header": [], "code": 410, "body": "{\"message\": \"Workflow execution history is no longer available.\"}", "name": "History unavailable" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Get the current call stack of a running workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/stack-trace", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/stack-trace", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Issues the built-in `__stack_trace` query against the workflow worker\nand returns the formatted stack trace as plain text. Only meaningful\nwhile the run is still executing; terminal runs return 409.\n\nThis is where the *workflow* is suspended, not where a step failed. For\nthe latter, a failed step's `error.frames` on the steps endpoint names\nthe line the node's author wrote." }, "response": [ { "header": [], "code": 200, "body": "{\"stack_trace\": \"coroutine ...\"}", "name": "Running" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run has no Temporal execution yet.\"}", "name": "Run not handed off to Temporal yet" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run is no longer running.\"}", "name": "Run is no longer running" }, { "header": [], "code": 410, "body": "{\"message\": \"Workflow execution history is no longer available.\"}", "name": "Execution unknown to Temporal" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Cancel a running workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/cancel", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"Superseded by a newer run\"}" }, "description": "Requests graceful cancellation of a still-running run: Temporal delivers a\ncancellation signal to the workflow, which may run cleanup before closing.\nThe run stays `running` until the next status reconcile flips it to\n`cancelled`, so this returns HTTP 202." }, "response": [ { "header": [], "code": 202, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"running\"}", "name": "Cancellation requested" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run is no longer running.\"}", "name": "Run already terminal" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Terminate a running workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/terminate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/terminate", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The run id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"Superseded by a newer run\"}" }, "description": "Forcefully terminates a still-running run with no cleanup and flips it to\n`terminated` immediately." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"workflow_id\": 1, \"status\": \"terminated\"}", "name": "Terminated" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run is no longer running.\"}", "name": "Run already terminal" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] }, { "name": "Re-run a previous workflow run", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/retry", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/retry", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The id of the run to re-run." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Starts a fresh run from the inputs (trigger payload + trigger handle) of\nan existing run, linking the new run to its source via\n`retried_from_run_id`. The source run may be in any state; the re-run\nalways executes against the workflow's currently-built bundle and runs\nasynchronously." }, "response": [ { "header": [], "code": 0, "body": "{\"message\": \"Workflow bundle is not ready (build_\"}", "name": "Workflow not runnable" }, { "header": [], "code": 202, "body": "{\"id\": 2, \"workflow_id\": 1, \"status\": \"running\", \"retried_from_run_id\": 1}", "name": "Accepted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow configuration has unresolved issues and cannot run. Fix the reported fields and try again.\", \"errors\": {\"blob.nodes.0.config.credentials\": [\"Required config field 'credentials' is missing.\"]}}", "name": "Unresolved manifest issues (PO-186)" }, { "header": [], "code": 422, "body": "{\"message\": \"No active trigger with handle ... exists on this workflow.\"}", "name": "Trigger no longer resolvable" }, { "header": [], "code": 503, "body": "{\"message\": \"Workflow worker is unavailable.\"}", "name": "Worker unavailable" } ] }, { "name": "Resume a failed workflow run from its failed step", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:workflowId\/runs\/:runId\/resume", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:workflowId\/runs\/:runId\/resume", "variable": [ { "id": "workflowId", "key": "workflowId", "value": "1", "description": "The workflow id." }, { "id": "runId", "key": "runId", "value": "1", "description": "The id of the failed run to resume." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"Superseded by a newer run\"}" }, "description": "Resets the underlying Temporal execution to the workflow-task boundary\nbefore the failed step and re-drives it: already-completed steps keep\ntheir results, the failed step and everything downstream re-execute. The\nresumed run is tracked as a new run linked via `resumed_from_run_id`." }, "response": [ { "header": [], "code": 202, "body": "{\"id\": 2, \"workflow_id\": 1, \"status\": \"running\", \"resumed_from_run_id\": 1}", "name": "Accepted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Run not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Only a failed run can be resumed.\"}", "name": "Run not resumable state" }, { "header": [], "code": 409, "body": "{\"message\": \"Workflow run has already been resumed.\"}", "name": "Already resumed" }, { "header": [], "code": 422, "body": "{\"message\": \"Workflow run cannot be resumed: no suitable reset point in its history.\"}", "name": "No reset point" }, { "header": [], "code": 503, "body": "{\"message\": \"Temporal is currently unavailable.\"}", "name": "Temporal unavailable" } ] } ] }, { "name": "Workflows", "description": "\nPer-tenant workflow definitions. Every endpoint is scoped to the tenant\nresolved by the `resolve.tenant` middleware (from the JWT or\n`X-Tenant-Id` header). Cross-tenant access deliberately returns 404 so\nthat the API does not leak the existence of resources owned by other\ntenants.", "item": [ { "name": "List workflows", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns the workflows owned by the current tenant, ordered by name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": 1, \"name\": \"Sync orders\", \"description\": null, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"active\": true, \"revision\": 1, \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}]}", "name": "Success" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Create a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Sync orders nightly\",\"description\":\"Pulls orders from the upstream API every night at 02:00 UTC.\",\"blob_definition_version\":\"v0-draft\",\"blob\":{\"nodes\":[],\"edges\":[]},\"active\":true,\"execution_mode\":\"async_only\",\"triggers\":[{\"handle\":\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",\"type\":\"webhook\",\"name\":\"PSP webhook\",\"config\":{\"method\":\"POST\"},\"active\":true}]}" }, "description": "Persists a new workflow under the current tenant. The `name` must be\nunique within the tenant. The `blob` is validated against the schema\nregistered for the supplied `blob_definition_version`." }, "response": [ { "header": [], "code": 201, "body": "{\"id\": 1, \"name\": \"Sync orders\", \"description\": null, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"active\": true, \"revision\": 1, \"warnings\": [], \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Created" }, { "header": [], "code": 422, "body": "{\"message\": \"The given data was invalid.\", \"errors\": {\"blob.nodes.0.config.credentials\": [\"Required config field 'credentials' is missing.\"]}}", "name": "Validation failed (structural, or manifest issues on an active save)" } ] }, { "name": "Show a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The workflow id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Returns a single workflow by id within the current tenant." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"name\": \"Sync orders\", \"description\": null, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"active\": true, \"revision\": 1, \"warnings\": [], \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T10:00:00Z\"}", "name": "Success" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Replace a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The workflow id." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Sync orders nightly\",\"description\":\"Pulls orders from the upstream API every night at 02:00 UTC.\",\"blob_definition_version\":\"v0-draft\",\"blob\":{\"nodes\":[],\"edges\":[]},\"active\":true,\"execution_mode\":\"async_only\",\"triggers\":[{\"handle\":\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",\"type\":\"webhook\",\"name\":\"PSP webhook\",\"config\":{\"method\":\"POST\"},\"active\":true}]}" }, "description": "Performs a full-replace update of the workflow with the given id. All\ndomain fields are required. The `revision` counter is incremented\nexactly when the supplied `blob` differs from the stored one, in which\ncase the previous revision is snapshotted into the workflow history." }, "response": [ { "header": [], "code": 200, "body": "{\"id\": 1, \"name\": \"Sync orders\", \"description\": null, \"blob_definition_version\": \"v0-draft\", \"blob\": {}, \"active\": true, \"revision\": 2, \"warnings\": [], \"created_at\": \"2026-05-06T10:00:00Z\", \"updated_at\": \"2026-05-06T11:00:00Z\"}", "name": "Updated" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] }, { "name": "Delete a workflow", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/workflows\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/workflows\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The workflow id." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" }, { "key": "X-Tenant-Id", "value": "acme-production" } ], "body": null, "description": "Removes the workflow identified by `{id}` for the current tenant.\nAssociated history rows are removed via cascade." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 404, "body": "{\"message\": \"Not found.\"}", "name": "Not found" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }