HTTP API

Calling workflows and unified endpoints over HTTP.

Every workflow's API tab shows its own endpoint and a copyable curl.

Base URL

The base URL is the deployment you are on: for example https://app.fastn.dev on the production platform. Your workflow's API tab always shows the correct one for your workspace; the examples below use YOUR_FASTN_HOST.

---

Authentication

Every request carries an API key as a bearer token.

Authorization: Bearer fsk_live_<your-key>

Keys are created under Settings → API keys and come in two modes.

Header	Live key	Test key
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	Any environment slug	Any environment slug

The rule that is enforced is the test-key one: a test key without X-fastn-Test-Mode: true is rejected. Do not read that backwards into an assumption about what a live key may or may not send.

x-fastn-env picks which code runs:

• test: the workflow's latest published version.

• any other slug: the version deployed to that environment.

A test key is not a sandbox. It reaches the same live connections as a live key and causes the same real writes.

---

Execute a workflow

POST /api/v1/workflows/{workflowId}/execute

The workflow id is shown on the workflow's API tab, in the form wf_b5880b29eb25.

curl -X POST https://YOUR_FASTN_HOST/api/v1/workflows/WORKFLOW_ID/execute \
  -H "Authorization: Bearer fsk_test_<your-key>" \
  -H "X-fastn-Test-Mode: true" \
  -H "x-fastn-env: test" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "saleId": "S-1024",
      "isRetry": false,
      "syncMode": "incremental"
    }
  }'

Request body

{
  "input": {
    "key": "value"
  }
}

The input object is what arrives as ctx.input. Its shape comes from the workflow's input contract.

Every workflow's API tab generates a ready-to-run curl filled in with that workflow's own host, id and contract fields. When the two differ, copy from there. It is generated from the deployment you are actually calling.

Response: Instant tier

The workflow's return value comes back inline, synchronously, within the tier's 30-second ceiling. Its shape is the workflow's own output contract: read it on the Contract tab rather than from an example here, because it is different for every workflow.

Response: Standard and Long tiers

202 Accepted with an execution id, in the form exec_…. The run continues in the background; the id is what identifies it afterwards in Executions, where each row expands to its input, output and per-step timings.

There is no documented endpoint for polling an execution id. If your caller needs to know the outcome of a Standard or Long run, have the workflow call you back at the end rather than assuming you can poll for it.

---

Scoping a call to a customer

fastn is multi-tenant: the same workflow serves all of your customers, and headers on the request are what say which one a call is for.

Header	Carries
x-end-org-id	The customer this call acts for.
x-end-org-ref	Your own reference for that customer.
x-installation-id	Which installation of the integration the call belongs to.
x-fastn-connections	The connections the run may use.
x-fastn-installation-config	The configuration values that installation was set up with.

Inside the workflow these arrive on ctx.headers. See Workflow runtime API. Exact value formats are on each workflow's own Docs tab, generated from the deployment you are calling; check there before you hard-code one.

---

Unified endpoints

Where a unified API covers an entity, call it directly rather than a specific connector.

GET  /api/v1/unified/crm/account?page_size=50
GET  /api/v1/unified/crm/account/{recordId}
POST /api/v1/unified/crm/account
POST /api/v1/unified/crm/note

fastn routes to whichever provider the customer authorised. Each endpoint on the Unified APIs page has a Copy curl button with the correct headers filled in.

---

Webhook endpoints

A webhook trigger gives you a public URL. Whether callers must authenticate is set on the trigger:

Authentication setting	Caller must send
API Key (x-fastn-access-key)	x-fastn-access-key: <your-key>
None (public)	Nothing

---

Embed tokens

Tokens that scope the widget to one customer. Mint them from your backend with your API key; never expose the API key to a browser.

Mint a token

POST /api/v1/embed/token

Header	Value
Authorization	Bearer <API key>
x-org-id	<orgId>

{
  "token": "emb_…",
  "endOrgId": "…",
  "role": "end_user",
  "expiresIn": 28800
}

expiresIn is 28800 seconds: eight hours. endOrgId is the customer the token is scoped to, and the returned role is always end_user.

Where the API key is pinned to specific customers, send {"endOrgId": "…"} in the request body instead of the x-org-id header.

Refresh

POST /api/v1/embed/token/refresh

Refresh is capped at seven days per session. At the cap the widget posts fastn:session-expired to the parent window and stops: refreshing again does not extend it. Listen for that message and start a new session by minting a fresh token. A host app that assumes refresh is indefinite will strand long-lived sessions.

Using the token

The iframe endpoint takes it on the query string:

https://YOUR_FASTN_HOST/api/v1/embed/iframe?token=emb_…

That URL carries a live credential. Treat it like one: build it server-side per session, and do not log or share it. Full setup in Embedding the widget.

---

Errors

Response	Means
WORKFLOW_NOT_PUBLISHED	The workflow has never had a snapshot published, so there is no version to run. Every call returns this until you publish one. It is the most common cause of "the API did nothing". Publish from the workflow editor.
401 / 403	The key is wrong, revoked, expired, outside its IP allowlist, or lacks the permission for what you called. Check the key on Settings → API keys.
Test key rejected	The key is a test key and X-fastn-Test-Mode: true was not sent.

A workflow that runs and throws is a Failed execution rather than a transport error: look for it in Executions, not in the HTTP response.

---

Rate limits

Per-day and per-minute ceilings on API calls and events are listed, with current usage, on Settings → Billing, which also carries per-customer limits. Going over stops new work rather than charging you, and nothing already running is interrupted, so a caller that suddenly gets nowhere is worth checking against that page before you debug the workflow.