REST API — Postman, curl & your own apps

The REST API is one of the two Platform Access surfaces — create / update / list every artifact over plain HTTP, authenticated by your Personal Access Token (get one here).

Authentication

Send your token as a bearer credential (or the X-API-Key header, whichever your client prefers):

Authorization: Bearer flowfn_pat_YOUR_TOKEN
# or
X-API-Key: flowfn_pat_YOUR_TOKEN

Base URL & choosing a team

REST base: https://api.flowfn.com/v1. Every action targets a team — if you belong to one it's used automatically; otherwise send the X-Team-Id: <team-id> header (or a ?team_id= query param). Call GET /v1/teams to find your team id. Most artifacts live under an app — omit app_id to use the team's first app, or pass a specific app_id.

Endpoint reference

Every resource supports GET (list) and POST (create); most also support PATCH …/:id (partial update). There is no delete in v1.

Discovery

Method	Path	Description
GET	/teams	List the teams you belong to (with your role).
GET	/connections	List the team's platform connections (no secrets). Optional ?platform_code=.
GET	/spec.json	OpenAPI 3 spec — import into Postman / Insomnia. Public, no token.

Apps

Method	Path	Required (create/update)
GET	/apps	—
POST	/apps	name, subdomain
PATCH	/apps/:id	any of name, description, is_active, accent_color, icon

Agents

Method	Path	Required / fields
GET	/agents	filters: app_id, type, search, limit, offset
POST	/agents	name, type (interactive|webhook|schedule|playground|streaming); optional task, description, app_id
PATCH	/agents/:id	name, description, task, is_active

Streams

Method	Path	Required / fields
GET	/streams	filter: app_id
POST	/streams	name; optional description, open_identity, app_id
PATCH	/streams/:id	name, description, status

Data sheets (database → sheet → rows)

Method	Path	Required / fields
GET	/databases	filter: app_id
POST	/databases	name; optional slug, description, app_id
GET	/databases/:dbId/sheets	—
POST	/databases/:dbId/sheets	name; optional slug, columns ([{ key, name, type, options? }])
PATCH	/sheets/:id	name, slug, columns
GET	/sheets/:id/rows	query rows: ?match={json}, limit, offset
POST	/sheets/:id/rows	rows: an array of { columnKey: value } objects

Playgrounds · Forms · Workflows · Visualizers

Method	Path	Required / fields
GET / POST	/playgrounds	create: name, slug
PATCH	/playgrounds/:id	name, description, status
GET / POST	/forms	create: title, slug; optional description
PATCH	/forms/:id	title, description, status, is_public
GET / POST	/workflows	create: name; optional description
PATCH	/workflows/:id	name, description
GET / POST	/visualizers	create: title, slug; optional visualization_type (table|line|bar|pie|area|number)
PATCH	/visualizers/:id	title, status

Examples

# List agents in your default team
curl https://api.flowfn.com/v1/agents \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" \
  -H "X-Team-Id: <your-team-id>"

# Create an agent
curl -X POST https://api.flowfn.com/v1/agents \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support bot","type":"interactive","task":"Answer product questions"}'

# Create a form
curl -X POST https://api.flowfn.com/v1/forms \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Waitlist","slug":"waitlist"}'

# Create a database + sheet, then insert rows
curl -X POST https://api.flowfn.com/v1/databases \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"CRM"}'
# → { "id": "<dbId>", ... }
curl -X POST https://api.flowfn.com/v1/databases/<dbId>/sheets \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Leads","columns":[{"key":"email","name":"Email","type":"text"}]}'
# → { "id": "<sheetId>", ... }
curl -X POST https://api.flowfn.com/v1/sheets/<sheetId>/rows \
  -H "Authorization: Bearer flowfn_pat_YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"a@example.com"},{"email":"b@example.com"}]}'

Responses, errors & limits

List endpoints return { "items": [...], "total": n }; create returns 201 with the new record; update returns 200. Errors use a consistent envelope:

{ "error": { "code": "limit_reached", "message": "Your plan allows 5 agents per team. Delete one or upgrade to add more." } }

Common codes: unauthorized (401, bad/missing token), forbidden (403, insufficient team role or the surface isn't in your plan), plan_locked (feature off), limit_reached (per-plan cap), slug_conflict, not_found, rate_limited (429 — a per-token burst cap; retry after a moment). The token is bound to your identity, so you can only touch teams you're a member of, with your role's permissions.