fastn for AI agents
A single dense page for LLMs and coding agents: the model, the runtime surface, the endpoints, and the things that are easy to get wrong.
This page exists for AI agents and other machine readers. It is deliberately terse and factual: no narrative, no screenshots, every exact string spelled out. Human readers are better served by Core concepts.
If you are an agent writing fastn workflows or calling the fastn API, read this page first, then confirm anything marked Verify against the live surfaces named at the bottom.
The model in six lines
An organization is you, the SaaS company. It holds everything below.
A connector defines an external system: its actions, auth methods and versions.
A connection is one of your customers' authorized link to one connector, holding the encrypted credential.
A workflow is JavaScript that runs on a trigger. It is code, not a drag-and-drop graph.
A trigger starts a workflow: webhook, schedule, or app event.
A widget is the embedded UI your customers use, inside your product.
fastn is multi-tenant throughout. One workflow serves every customer; headers on the request decide which customer a run acts for.
Workflow anatomy
A workflow is an async function receiving a context object.
export default async function (ctx) {
const { recordId } = ctx.input;
const record = await fastn.connector.hubspot.getContact({ recordId });
return { ok: true, id: record.id };
}The file is
<slug>.js. The export is default and async.The Diagram tab is generated from this code and is read-only. There is no visual editor to keep in sync.
Drafts autosave as you edit; Save workflow saves the workflow itself.
Whatever you return must match the workflow's declared output contract.
Throwing marks the execution Failed. A throw in your own code is not retried. (On Standard and Long, an uncaught connector 5xx error is retried; a workflow's retry policy is only read by the Instant tier's timeout retry.)
ctx
ctx.input
The incoming payload. Webhook → request body. Schedule → the route's Payload JSON. App event → the connector's event payload. Manual/API → the input object from the request body.
ctx.headers
HTTP headers from the incoming request, including the customer headers below.
Runtime surface
fastn.connectors.<slug>.<action>(args)
Call an action on a connected system. fastn.connector.<slug>.<action>(args) (singular) also works. See the caveat below.
fastn.unified.…
Call a unified entity and let fastn route to whichever provider the customer connected.
fastn.db.query(sql, params)
SQL against your workspace's Postgres schema (ws_<hash>). Verify signature.
fastn.state.get(key) / fastn.state.set(key, value)
Durable key-value across runs. Scopes: ORG, INVOCATION.
fastn.secrets.get("NAME")
Read an encrypted secret. Name is UPPER_SNAKE_CASE, exactly as created. JSON-typed secrets return already parsed.
fastn.envConfig.get("KEY")
Read a per-environment config value.
fastn.diff.compare(…)
Produce a sync report. A workflow that does not call this produces no report.
Execution tiers
Instant
Return value inline, synchronously
25 seconds (2 minutes if fastn has raised the Instant timeout for your organization)
Standard
202 + execution id
15 minutes
Long
202 + execution id
36 hours (the maximum the dashboard allows)
Instant is the default. Anything calling two or three systems in sequence belongs on Standard.
Customer headers
Sent on the request; readable at ctx.headers.
x-org-id
The customer the run acts for: your own id for it, or fastn's id for it
x-installation-id
Which installation of the integration this run belongs to
x-fastn-connections
The connections the run may use
x-fastn-installation-config
The configuration values that installation was set up with
HTTP API
Production base URL: https://api.fastn.dev. Your workflow's API tab shows the URL for your workspace. Examples below use YOUR_FASTN_HOST.
Auth
Authorization
Bearer fsk_live_…
Bearer fsk_test_…
X-fastn-Test-Mode
Not needed
Must be true: a test key is refused without it
x-fastn-env
Environment slug (a key made for one environment may name only that environment and test)
test only: any other slug is refused with 403 ENV_NOT_PERMITTED
X-API-Key: fsk_… works in place of Authorization. A webhook trigger URL takes the key in either of those, or in x-fastn-access-key. No endpoint reads x-fastn-api-key.
x-fastn-env: test runs the latest published version; any other slug runs the version deployed to that environment. Omit the header and it follows the key: a test key gets test, a live key gets live.
Endpoints
Workflow ids look like wf_b5880b29eb25; execution ids like exec_…; embed tokens like emb_….
Execute request body: the input object becomes ctx.input:
Unified API categories
The categories, entities and providers are catalog data and change over time, so do not hard-code a list. Read them from the API: GET /api/v1/unified/categories, and GET /api/v1/unified/{category}/{entity}/providers for the providers behind one entity. Examples of categories: CRM, Documents, Messaging; examples of CRM entities: Account, Contact, Lead, Opportunity. Note and message entities are create-only.
Errors
WORKFLOW_NOT_PUBLISHED
No snapshot has ever been published. Every call returns this until one is. The single most common cause of "the API did nothing".
401 / 403
Key wrong, revoked, expired, outside its IP allowlist, or lacking the permission.
Test key rejected
X-fastn-Test-Mode: true was not sent with a test key.
A workflow that runs and throws is a Failed execution, not a transport error. Look in Executions, not the HTTP response.
Polling depends on the tier:
Instant answers
200with the workflow's return value. The execution id is in theX-Execution-Idresponse header. Nothing to poll.Standard and Long answer
202withdata.executionId. PollGET /api/v1/workflows/{workflowId}/executions/{executionId}for the result.
Triggers
Webhook
An HTTP request arrives at a public URL
Auth (API key in X-API-Key, Authorization: Bearer or x-fastn-access-key, or public), routes, execution mode (Parallel/Sequential), deduplication key
Schedule
A time is reached
Cron/interval, plus a Payload JSON that becomes ctx.input
App event
Something changes in a connected system
Connector, connection, event, routes
Two different MCP surfaces
Do not conflate these.
URL
<docs-site>/~gitbook/mcp
https://mcp.fastn.dev/fastn-workspace
Exposes
This documentation, as searchable tools
Your fastn workflows and the fastn platform tools (connector actions run through platform tools such as executeAction)
Auth
Public, as the docs site is
OAuth sign-in: the client sends you to fastn to sign in, and to pick a workspace if you belong to more than one org
Use for
Answering questions about fastn
Acting on real customer systems
Claude Code, against the product gateway:
A gateway client acts as you, in the workspace you picked when signing in, with your own role there. Per-client setup: MCP gateway.
Things agents get wrong
Read this section before generating code.
fastn.connectorvsfastn.connectors. Both work. On save, fastn scans the code forfastn.connectors.<slug>.<action>(…)and<instance>.connector.<slug>.<action>(…)calls and binds those connectors. A dynamic call such asfastn.connectors[slug]cannot be detected: add that connector to the workflow by hand on its Connectors tab.fastn.stateORGkeys are shared by every workflow in the org.INVOCATIONkeys live for one execution. NamespaceORGkeys by workflow (myworkflow:deal:123) so two workflows do not overwrite each other.Don't rely on
fastn.dbto separate customers. Which schema a query runs in depends on your organization's database setup. If a table holds data for several customers, add a customer column and filter on it in every query.Always parameterize SQL. Interpolating
ctx.inputinto a query string is an injection.Publishing is not optional. Code that is saved but not published does not run over the API.
Instant's 25-second ceiling is hard, and finding out by timing out in production is expensive.
Embed refresh caps at seven days per session. At the cap the widget posts
fastn:session-expiredto the parent window and stops. Listen for it and mint a fresh token.Connector credentials are not secrets. They live on connections and are managed by fastn, including OAuth refresh.
fastn.secretsis for third-party tokens and keys you hold yourself.Settings is role-scoped. What a user can see under Settings depends on their role, so do not assume a screen exists for the current user.
Authoritative surfaces
Generated from the deployment you are actually calling, and therefore more trustworthy than any document. This one included:
Workflow → Diagram tab → Docs
Exact runtime call shapes and header value formats for your deployment
Workflow → Contract tab
The real input and output shapes
Workflow → API tab
A ready-to-run curl with your host, workflow id and contract fields
Workflow → Connectors tab
Which connectors and action versions are actually bound, and per-customer vs workspace scope
Connector detail page
The action list, and the Select all control that scopes them
When this page and a generated tab disagree, the tab is right.
Machine-readable formats
This documentation is published from GitBook, which serves it in agent-friendly formats without configuration:
/llms.txt
A curated index of the documentation
/llms-full.txt
The entire documentation as one markdown file
<any page URL>.md
That page as raw markdown
/~gitbook/mcp
The documentation as an MCP server
Prefer llms-full.txt for a single bulk load, the MCP server for interactive lookup.
Last updated
Was this helpful?

