Using the Routario API

Most of what you do in Routario, you do in the app or in a flow. But when you need an external system to push data in or pull results out, Routario has a REST API.

The API is Bearer-authenticated and scoped, and it covers three things:

• Custom Tables — read and write the rows in your data tables.
• Workflow runs — trigger a flow and inspect the result of a run.
• Memory ingestion — send documents and notes into Memory so Routario can read and file them.

Full reference lives at routario.com/api

This page is an orientation. Every endpoint, parameter, and response — with a built-in “try it” console — is in the complete API reference, generated from Routario’s OpenAPI specification so it’s always current.

Authentication

Every request carries an API token in an Authorization header:

Authorization: Bearer <your-token>

Create a token in Settings, keep it secret (treat it like a password), and give it only the scopes it needs. If a token leaks, revoke it and issue a new one.

When to reach for the API

You usually don’t need the API — a flow can do most integration work with a Webhook trigger (data in) or a Webhook step (data out). Reach for the REST API when:

• An external system needs to push rows into a Custom Table on its own schedule.
• A backend service needs to trigger a flow and read its result synchronously.
• A pipeline needs to feed documents into Memory for Routario to process.

Starting a flow from outside: Webhook trigger vs. the Run API

Two different ways to let an outside system start a flow, and they’re easy to mix up. Both end up in the same place — the caller’s data lands in payload — but they’re provisioned differently, authenticate differently, and suit different callers.

	Webhook trigger	Run API (POST /api/v1/runs)
What it is	A trigger node on one specific flow’s canvas	An endpoint that starts any flow, named by id in the request body
When to use	One external sender (Stripe, GitHub, a payment gateway) needs to push data into that one flow	A backend or script needs to trigger a flow and read the result back — or the same credential needs to drive several different flows
How to provision	Add a Webhook trigger to the flow’s canvas; copy the URL from its panel (/flows/webhook/<workflow_id>)	Settings → Connections → API keys → Generate key
Authentication	An optional shared secret, sent as X-Webhook-Secret	A Bearer token, sent as Authorization: Bearer <token>
Is a secret/token required?	Yes, effectively — Routario refuses to fire a webhook with no secret configured (fails closed)	Yes, always — there’s no anonymous call; the token itself is the credential
Scopes	None — it’s all-or-nothing for that one flow	Fine-grained, per key: pick run:<workflow-id> or run:* (every workflow), each with independent Read (poll a run) / Write (start a run) — alongside Table and Memory scopes on the same key
Rate limit	Fixed at 60 requests/minute for that flow’s URL	Configurable per key (default 30 run-starts/minute), plus a cap of 5 runs executing concurrently per key
{{ user.* }} / {{ actor.* }} resolve to	The flow’s owner (whoever created it)	The API key’s own identity — a dedicated actor stamped to that key when it’s generated
What you get back	{run_id, status}	{run_id, status, output, error, started_at, updated_at} — plus GET /api/v1/runs/{id} to poll a WAITING run through to completion
Reachability	Routario must be reachable from the caller (automatic in the hosted product; a tunnel like Cloudflare Tunnel or ngrok if self-hosted)	Same requirement

Rule of thumb: if it’s one sender and one flow, and you never need to read the outcome back, the Webhook trigger is simpler to set up — no key management, just a URL. Reach for the Run API when one integration needs to drive several flows under one credential, when the caller needs the run’s output synchronously (or by polling), or when you want scopes and expiry independent of any single flow’s own configuration.

The Run API works even on a flow with no Webhook trigger

POST /api/v1/runs starts a flow by id regardless of what trigger is configured on its canvas — including Manual. That’s exactly the shape for a flow with no real external trigger of its own, meant to be driven entirely by another system (a cron job elsewhere, a script). See Running & debugging a flow for how to develop and test one of these by hand, with a sample payload, before anything external ever calls it.

Where to go next

• Complete API reference — every endpoint, with examples and a try-it console.
• Connect an AI agent over MCP — give an AI agent governed, scoped access to your workspace.
• Webhook trigger — start a flow from an external system with just a URL.
• Template variables — where payload comes from and how to reference it in a flow.
• Working with data: tables and imports — the in-app side of the tables the API reads and writes.