API conventions

Flow’s customer API uses HTTPS and JSON. Send X-API-Key and customer on every request, and Content-Type: application/json when sending a JSON body.

Scope each request

Most resource endpoints start with /project/{projectId}. Use the project’s id from GET /project, rather than its name or slug. If you have a slug, resolve it with GET /project/slug/{slug} first. Keep resource identifiers within the workspace and project that returned them. Send the workspace identifier in the customer header.

Identifier	Where to find it	Where to use it
Project ID	`GET /project` → `id`	`/project/{projectId}/...`
Category ID	`GET /project/{projectId}/data-model` → `id`	Entity list `entity_type`; create body `entityType`
Field key	Data model category → `fields[].key`	Value update `key`; entity `values` keys
Entity ID	Entity response → `id`	Entity paths and update body `entityId`
Branch ID	`GET /project/{projectId}/branch`	Branch parameter documented for the endpoint
Automation run ID	Trigger response → `results[].agent_id`	Poll query `agent_ids`

An entity’s uniqueEntityNumber is not a substitute for its id. Display names and custom field definitions can differ across projects even when the API contract is the same.

Select a branch

Entity reads and writes accept the Base alias master. Omitting the branch on these endpoints also selects Base. To work on a branch, pass its ID explicitly. Parameter names differ by endpoint:

Request	Branch field
`GET /project/{projectId}/entities`	Query `branch_id`
`GET /project/{projectId}/entities/{entity_ids}`	Query `branch_id`
`POST /project/{projectId}/entities/batch`	JSON `branchId`
`PUT /project/{projectId}/entities/values/batch`	JSON `branchId`
`POST /project/{projectId}/entities/history`	JSON `branch_id`
`POST /project/{projectId}/entities/filter/query`	JSON `branch_id`
`GET /project/{projectId}/entities/search`	Query `branch_id`

Keep the same project, branch, and filters throughout a paginated read. Follow each endpoint’s schema for exact spelling.

Protected branches

Entity writes honor branch protection and editor groups by default. On supported entity write endpoints, a personal API key owned by a project admin can pass the query parameter bypass_branch_protection=true to bypass those two restrictions, including on Base. The parameter defaults to false. Item locks, stage policies, field validation, and branch lifecycle checks still apply. Review the endpoint’s parameters before using this override.

Read every page

Pagination is specific to the endpoint.

Endpoint	Request	Response and stopping condition
List entities	Start with `starting_after=0`; then pass `nextPageStart` as `starting_after`. Default `limit` is 50; maximum is 1000.	Read `items`; continue while `moreAvailable` is `true`, including after an empty page.
Search branches	Use `offset` and `limit`.	Read `branches`; continue while `has_more` is `true`.
Entity history	Send JSON `cursor` from the previous `next_cursor`. `limit` is 1–100.	Read `items`; stop when `next_cursor` is `null`.
Filter entities	Send JSON `cursor` from the previous `next_cursor`, keeping the same filter and branch. `limit` is 1–100.	Read `entity_ids`; stop when `next_cursor` is `null`, including after an empty page.
Deleted entities on a branch	Send query `before` with the last row’s `cursor`.	Read `items`; stop when `next_cursor` is `null`.
List projects	Optional `limit`.	Returns an array without a continuation cursor. Omit `limit` to list all accessible projects.

Treat cursors as opaque strings. For entity lists, prefer starting_after to legacy offset; offset must stay below 1000 and is ignored when starting_after is set. See Read entities for a complete cursor loop.

Handle errors and retries

Check the HTTP status before consuming a success response. Keep the error response body for troubleshooting, while excluding API keys from logs.

Status	Next action
`400`	Correct the request’s identifiers, field names, types, or limits before retrying.
`401`	Check the API key and its revocation state.
`403`	Check the workspace identifier and the key owner’s access to the requested resource or action.
`404`	Verify the resource ID in the selected project and workspace.
`409`	Follow the endpoint’s conflict guidance. For an expired entity-history cursor after a rebase, restart pagination without the cursor.
`429` or transient `5xx`	For reads, retry with bounded exponential backoff and jitter. Honor `Retry-After` when present.

A timeout does not establish whether a write committed. Read back the affected resources before repeating a create, batch write, or automation trigger. Repeated triggers can start additional runs. See Batch writes for transaction boundaries.

Quickstart

Automations

Flow MCP

Endpoints

API conventions

Scope each request

Select a branch

Protected branches

Read every page

Handle errors and retries

​Scope each request

​Select a branch

​Protected branches

​Read every page

​Handle errors and retries

Scope each request

Select a branch

Protected branches

Read every page

Handle errors and retries