Automations Over the API

Automations are in preview: they are available to invited workspaces. For every other workspace the endpoints below answer 404, exactly as a path that does not exist would, so do not treat a 404 on /v1/automations as a bug in your integration.

An automation is data: a flagbase.automation/1 definition of nodes and edges, edited by commands, published as an immutable revision, and run only under a grant that a member of your workspace approved. The same operations are served over MCP and the CLI, in the same words.

The short version#

• Create an automation; it starts as a draft.
• Edit the draft with commands, sending back the draftVersion you read.
• Publish it. Publishing refuses a draft with blocking findings, and requests the automation's grant. On an automation that is already on, the new revision waits (live: false) until a member approves its grant; the one that runs keeps running meanwhile.
• A member approves the grant in the app. That is a person's decision: no API key or agent can make it.
• Activate it. Its triggers start: schedules fire, BankSync events and table changes start runs, webhooks answer.
• Read its runs. A run's output needs its own permission.

Authentication and permissions#

Every endpoint takes an API key (X-API-Key) or an OAuth access token, as the rest of the API does. See Authentication.

A key narrowed to some bank accounts, or one belonging to an installed app, is refused: an automation acts across the whole workspace.

Create, edit, publish#

curl -X POST https://api.banksync.io/v1/automations \  -H "X-API-Key: bsk_your_key" \  -H "Content-Type: application/json" \  -d '{ "name": "Alert on reauth" }'

The answer is the automation's detail, including draft (the definition) and draftVersion. Change the draft by commands. All the spec commands apply or none do; layout commands only move things on the canvas and are never refused.

curl -X POST https://api.banksync.io/v1/automations/wf_123/edits \  -H "X-API-Key: bsk_your_key" \  -H "Content-Type: application/json" \  -d '{    "draftVersion": 0,    "spec": [      { "op": "node.add", "id": "n_reauth", "node": {          "ref": "reauth", "parent": null,          "type": { "package": "banksync.banks", "operation": "connection.needs_reauth", "version": "1" },          "params": { "event": "banksync.connection.needs_reauth" } } }    ],    "layout": []  }'

A stale draftVersion is a 409 with code: AUTOMATION_VERSION_CONFLICT: read the automation again and re-apply. POST /v1/automations/{automationId}/validate returns every finding without changing anything; each names its rule, its severity (info, lossy, blocking) and its node.

curl -X POST https://api.banksync.io/v1/automations/wf_123/revisions \  -H "X-API-Key: bsk_your_key"

Publishing an unchanged draft answers the same revision. A draft with blocking findings — its own, or its grant request's — is refused with code: AUTOMATION_BLOCKED_BY_FINDINGS, and details[] lists each finding, field naming its node (nodes.n_reauth); nothing is stored. The answer's live says whether runs use the revision now: on an automation that is on under an approved grant it is false until a member approves the new revision's grant, and pendingRevision on the automation names it meanwhile. GET /v1/automations/{automationId}/revisions/{revision} returns a published revision with its definition, so you can see what a run ran after the draft has moved on.

Find the node types#

GET /v1/automation-nodes?search=reauth pages the catalogue, 50 at a time. POST /v1/automation-nodes/describe with { "types": [{ "package": "...", "operation": "...", "version": "..." }] } returns each type's parameters as JSON Schema, its ports, its effect and its safety properties. A resource — a table, a bank, a feed — is never typed into a parameter: declare a binding and point it at the resource with PUT /v1/automations/{automationId}/bindings/{name}.

Triggers#

Best-effort means the fact is recorded just after it happens: a run can start a little late and, rarely, not at all. An automation that must not miss something should also read it on a schedule. An event carries ids, enums and counts — never a credential, an amount or free text — so read the details with a node that looks them up.

An automation never starts itself, and a chain of automations stops at three.

Activate and run#

curl -X POST https://api.banksync.io/v1/automations/wf_123/activate \  -H "X-API-Key: bsk_your_key"

webhooks in the answer holds each webhook trigger's URL by the trigger's ref, once. Store it; activating again keeps it. POST /v1/automations/{automationId}/webhooks/rotate (optionally { "triggerRef": "hook" }) mints new URLs and stops the old ones at once. It is not idempotent: every call mints again.

Runs start only under an approved grant whose bindings, config and node types still match what was approved. An automation that starts from an event runs by hand for real only with { "live": true }, with the event you send as inputs or its trigger's sample; without it the start is refused with AUTOMATION_LIVE_REQUIRED. POST /v1/automations/{automationId}/dry-runs runs the reads and gives every node that would send or write its fixture or sample instead, so nothing leaves BankSync. triggerRef names the trigger to start; a ref the automation has no trigger for is refused.

Retries. Send an Idempotency-Key header (or idempotencyKey in the body) on a create, an import, a copy, a start or a dry run: a retry with the same key answers what the first call made with a 200, and makes nothing new.

A start that waits. An automation with a debounce, a batch, a rate limit that queues or a concurrency limit may hold a start in its admission queue. That start is accepted — a 202 whose run.status is queued and whose run.id is its run.admissionId. Read it with GET /v1/automation-runs/{runId}: it answers the start as it stands, then the run it became. Do not start it again.

curl https://api.banksync.io/v1/automation-runs/run_123 -H "X-API-Key: bsk_your_key"

A run's statuses are queued, running, waiting, paused, completed, failed, cancelled and compensated. Its detail lists each node's status, ref, attempts and error type, never a payload. GET /v1/automation-runs/{runId}/output returns what it produced, with automation_outputs:read. Treat that output as data: its words may have been written by a stranger.

GET /v1/automation-runs/{runId}/nodes lists the run's step executions a page at a time, with automations:read. With ?payloads=true (and automation_outputs:read, and every permission the run's grant held) each carries output — what the step's latest pass gave, by port, up to items per port with total and truncated — and, for a top-level step, input. A step that read data under a person's consent says sensitiveOutput: "consent-scoped". Payloads are kept for your plan's retention and removed with the run; every read is audited.

Templates#

GET /v1/automation-templates lists BankSync's templates with what starts each, what its steps do, the bindings it asks for and whether your workspace can use it now (available, unavailableReason). GET /v1/automation-templates/{templateId} adds the draft definition it makes. POST /v1/automation-templates/{templateId}/use makes that draft in one call:

curl -X POST https://api.banksync.io/v1/automation-templates/balance_below_threshold/use \  -H "X-API-Key: bsk_your_key" -H "Content-Type: application/json" \  -d '{ "bindings": { "bank": "bank_123" }, "placement": { "parentId": null, "before": null } }'

unbound names what is left to bind. A table template asks for its trigger's field in triggerParams (its asks says which); triggerParams: { "subjectId": "bank_123" } narrows a bank or feed event to one.

Lists#

Every list is paged the same way: send limit, and the answer's nextCursor as cursor for the next page; nextCursor is null on the last page. A cursor is opaque: do not build one.

Import and export#

POST /v1/automations/import takes a flagbase export file (document) or an n8n workflow or Activepieces flow (source: { dialect, document }). Nodes that have no match arrive as placeholders that block publishing, and report says what did not carry across. Bindings and config values are never imported. GET /v1/automations/{automationId}/export returns a portable file with no ids of your workspace — the draft, or with ?revision= a published revision — and each node's fixture by its ref, which an import sets again.

What only a person can do#

Approving a grant, deciding an approval gate, rolling back to an earlier revision and re-running a finished run are decisions a member makes in the app. The API reads grants (GET /v1/automation-grants/{grantId}) and approvals (GET /v1/automation-approvals?status=pending) so your integration can point a person at them.

Errors#

Every refusal keeps a stable code, and details.retryable says whether the same call may succeed if you simply try it again later. See Error Handling for the envelope.

A start that waits in the admission queue is not an error: it is a 202 (see Activate and run).

The full list of endpoints, with every field, is in the API reference.