Flow API: basics
The Flow API is the HTTP interface your server uses to work with Flow data: read and create objects, move them through statuses, run queries, and configure types, automations, processes and webhooks. It is the same API the Flow interface on sensever.com uses: anything a person does in the interface, a program does with the same requests and the same permissions.
This article covers the general rules: base URLs, authorization, headers, errors, limits, pagination and the full list of methods. For a step-by-step example, see Flow API: your first integration in 15 minutes. Workspaces, types and statuses are explained in Flow: introduction.
Base URLs
API | Base URL | What is available |
|---|---|---|
Flow API |
| The full contract: objects, schema, views, automations, processes, webhooks, reports, access |
Flow API via the unified Sensever API |
| The same contract and the same key; paths are the same as for |
Legacy gateway (deprecated) |
| A limited set of methods (see below). Shuts down on October 13, 2026 |
All requests must use HTTPS. Paths in the "Flow API" articles are relative to the base URL: POST /objects means POST https://flow.sensever.com/v1/objects.
For integrations, use https://flow.sensever.com/v1 or https://api.sensever.com/v1/flow. The legacy gateway is kept for compatibility only: it forwards a subset of methods to Flow and returns its own rejections as errors in the unified Sensever API format. Its responses carry the headers Deprecation: true, Sunset: Tue, 13 Oct 2026 00:00:00 GMT and Link: <https://api.sensever.com/v1/flow/…>; rel="successor-version" — the replacement URL with the same path.
Migrating from the legacy gateway
Replace the beginning of the URL; everything else stays the same — the key, X-Workspace-Id, the body and the path:
Before | After |
|---|---|
|
|
|
|
After October 13, 2026, the old URLs may be shut down without further notice.
What the legacy gateway sensever.com/api/v1/flow forwards
Method | Paths (relative to |
|---|---|
|
|
|
|
|
|
Gateway specifics:
the type in the path must be a UUID; the gateway does not accept a type key (
task);no more than 120 requests per minute;
only the headers
X-Workspace-Id,Idempotency-Key,If-MatchandX-Request-IDare passed to Flow; Flow does not useIf-Match— the object version goes in theexpected_versionbody field;the gateway itself answers
403 forbiddento a key without Flow access, a read-only key on a write request, and a workspace not in the key; a path outside the list gets404 not_found; a failure or a 5xx from Flow gets503 dependency_unavailable. All other Flow responses are passed through as is;GET /methrough the gateway works only in a person's session: an API key gets401(see Flow API: workspace, access and notifications).
Authorization
API key from your Sensever profile
The main option for integrations is a Sensever platform key. A person issues it in their profile on sensever.com: Profile → API (https://sensever.com/profile/api), the "API keys" form:
"Key name" — for example, "Company website".
In the Flow block, choose the access level: "No access to Flow", "Read-only" (objects, types and views of the selected workspaces) or "Read and write" (creating and changing objects, status transitions).
Select the Flow workspaces the key will work in. A key with Flow access cannot be created without at least one selected workspace.
"Expiration": 30, 90 (default), 180 or 365 days, or "No expiration" — until revoked.
"Create key". The full key is shown only once — copy it right away.
The same key can also carry chat and publishing permissions — one key works across all Sensever products. You can revoke a key in the same place with the "Revoke" button.
Pass the key in a header together with the workspace:
Authorization: Bearer ak1.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
X-Workspace-Id: 0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70How the key works:
The key acts on behalf of the person who issued it. In Flow it gets exactly that person's permissions as a workspace member, never more.
X-Workspace-Idis required and must be one of the workspaces selected in the key. You can find the workspace UUID in the Flow interface URL:https://sensever.com/flow/w/<workspace UUID>/….A "Read-only" key allows any
GETand two queries —POST /objects/queryandPOST /objects/available-actions. Everything else gets403, including requests that only read data but are sent withPOST: running a viewPOST /views/{id}/query, reportsPOST /reports/…, batch readsPOST /objects/relations,POST /objects/subtask-progress,POST /time/totals,POST /recurrence/lookupand recurrence preview. These need a "Read and write" key.The key does not depend on the session it was created in: signing out of Sensever, changing your password or "sign out everywhere" do not stop it. The key stops working when it is revoked, when it expires, or when the Sensever account is disabled.
Flow verifies the key with Sensever Accounts and caches the answer for 60 seconds, so revoking a key reaches Flow within a minute.
Store the key on your server only. Never put it into HTML, browser JavaScript, a mobile build or a public repository.
Key-related rejections (403 PERMISSION_DENIED, the reason is in error.details.reason):
| Meaning |
|---|---|
| The key has "No access to Flow" selected |
| The workspace from |
| The key is "Read-only", but the request changes something |
| The key owner is not a member of this workspace or has never signed in to Flow |
| The member is disabled in the workspace |
| The key owner's Sensever account is disabled |
| A workspace key ( |
Without X-Workspace-Id, a request with a platform key gets 422 VALIDATION_FAILED with the field header.X-Workspace-Id. An invalid, revoked or expired key gets 401 UNAUTHENTICATED. If Flow cannot verify the key because Accounts is down, the response is 503 SERVICE_UNAVAILABLE (retry later), not 401.
Workspace key flw_…
A workspace also has its own service keys of the form flw_<prefix>_<secret>. A member with the integration.manage permission issues them with POST /api-credentials; they are not available in the Flow interface. Such a key is bound to one workspace: X-Workspace-Id is not needed with it and is ignored. You can narrow the key's permissions with scopes (scopes), for example object:read or object:*. Details are in Flow API: workspace, access and notifications.
A member's keys are revoked automatically when the member is disabled or removed from the workspace.
Key scopes
A scope is a resource:action pair taken from role permissions, for example object:read, object:update, schema:manage. A method requires the same permissions a person needs in the interface, so a key with scopes needs the scopes for those permissions. For methods added since 25.09:
Methods | Required scopes |
|---|---|
|
|
|
|
|
|
|
|
Another member's time ( |
|
|
|
|
|
|
|
|
|
A missing scope gets 403 PERMISSION_DENIED with details.reason = key_scope.
What is not suitable for integrations
The browser session (the flow_session cookie) and the embed token (a JWT that sensever.com obtains for its own Flow interface) are how the interface itself signs in. The embed token lives for 10 minutes and is issued only to the sensever.com server. Integrations do not use them.
Some methods work only with a session or an embed token — they concern a person across all of their workspaces at once, while a key is always bound to specific workspaces. An API key (both ak1.… and flw_…) gets 401 UNAUTHENTICATED on them; X-Workspace-Id is not needed and is ignored:
GET /me,POST /workspaces,GET /invitations,POST /invitations/{workspace}/{invitation}/respond;everything under
/me/…:POST /me/objects/query,POST /me/objects/calendar,GET /me/objects/filters,GET /me/approvals,POST /me/reports/summary,GET /me/tasksand the other "By section" methods,GET,POST,DELETE /me/calendar-feeds…,GET,PATCH /me/mail-settings.
An integration that needs data from several workspaces iterates over them itself with the appropriate X-Workspace-Id.
GET /calendar-feeds/{token} is the only public method apart from health checks: it returns a calendar in iCalendar format via a secret subscription link, with no session or key. Details are in Flow API: personal lists, calendar and email.
Headers
Header | Direction | Purpose |
|---|---|---|
| request | API key ( |
| request | Workspace UUID. Required for a platform key, ignored for a |
| request | The body is JSON in UTF-8 (except CSV uploads) |
| request | Key for safely retrying a change, 8–255 visible ASCII characters |
| request and response | Your request ID (8–128 characters |
| request | Compact response for commands that change definitions |
| response | The server applied |
| response | The response is a replay of the stored response for the same |
| response | How many seconds to wait before retrying ( |
| request | Client version |
Flow does not use ETag and If-Match: concurrent changes are protected by the expected_version field in the request body.
Idempotency-Key: safe retries
You can safely retry a write request after a network error if you send the same Idempotency-Key:
the key is stored for 24 hours and belongs to the caller; the first response is stored byte for byte and returned again with the
Idempotency-Replayed: trueheader — including 4xx business errors, except409 OBJECT_VERSION_CONFLICTand429;the same key with a different method, path, body or
Prefergets422 IDEMPOTENCY_KEY_REUSED;while the first request with this key is still running, a retry gets
409 IDEMPOTENCY_IN_PROGRESS;5xx responses are not stored: the change is rolled back, and a retry with the same key runs again from scratch.
The key is required for POST /objects, transitions POST /objects/{id}/transitions/{transition_key}, background operations POST /operations, starting a process POST /processes/{key}/start and external events POST /events. Without it you get 422 VALIDATION_FAILED with the field header.Idempotency-Key. For other changes the key is optional but recommended. Queries (POST /objects/query and similar) do not use the key.
Generate a new key (for example, a UUID) for each logical action and keep it until you get a response. Do not create a new key when retrying after a timeout — otherwise the object may be created twice.
expected_version: protection against concurrent changes
An object has a version number, version, which increases with every change. Changing an object (PATCH /objects/{id}) requires expected_version — the version you read. If the object has been changed in the meantime, the response is 409 OBJECT_VERSION_CONFLICT: re-read the object and apply your change to the new version. In a transition, expected_version is optional: without it, the current version is used.
Prefer: return=minimal
Commands that create and change definitions (schema and status process versions, views, automations, processes, roles — 21 methods) respond with the full definition by default. With the Prefer: return=minimal header, they return a compact DefinitionResult:
{
"representation": "minimal",
"resource": "schema_version",
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"version": 3,
"status": "draft",
"href": "/v1/schema-versions/0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70"
}Read the full state with GET href. Even without Prefer, the server returns the compact result if the full definition is larger than 64 KB, so check the representation field before parsing the response. More in Flow API: types, fields, statuses and publishing.
Requests and responses
The request body is a JSON object. An unknown field in the body is usually rejected with
422 VALIDATION_FAILED, so do not send extra fields.The response is JSON with status
200or201. Export returns a CSV file.Time is an RFC 3339 string in UTC, for example
2026-09-25T08:00:00Z.IDs of objects, types, versions and members are UUIDs (UUIDv7 for those created by the platform). Types, fields, statuses, transitions and actions also have a stable machine key (
key, up to 64 characters), for exampletask,due_date,in_progress. Where a method accepts "a key or an id", you can pass either.
Compatibility
The API evolves only by additions within /v1: fields, values and methods are never removed or renamed without /v2. So your client must:
ignore unknown response fields;
handle unknown enum values (new statuses, reasons, kinds);
treat an unknown
error.codeas a generic error of its HTTP status.
Do not treat your own copies of business checks as final: the API always decides whether a transition is available and what is permitted. To show available transitions in advance, use GET /objects/{id}/available-actions.
Pagination
Lists are read with cursors (keyset). In the request, pass page.size from 1 to 200 (default 50) and page.cursor; in GET methods, use the parameters page[size] and page[cursor]. The response contains:
{
"items": [],
"page": { "size": 50, "next_cursor": "eyJ2Ijox…" }
}Pass next_cursor as page.cursor to get the next page; null means the last page. The cursor is opaque: do not parse it or build it yourself. A cursor is valid only for the same query (same type, condition and sort); someone else's or a modified cursor gets 422 VALIDATION_FAILED with the field page.cursor.
Errors
Every error is JSON with a 4xx or 5xx HTTP status in a single envelope:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validation failed",
"details": {
"fields": [
{ "field": "fields.due_date", "code": "invalid_format", "messages": ["…"] }
]
},
"request_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70"
}
}Your code should rely on error.code and error.details, not on message: the message is for logs and developers, and its text may change. details is an empty object if there are no details. For some codes, details is always present:
| What is in |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
details.fields contains at most the first 100 errors and at most 32 KB. If there are more errors, details has truncated: true and fields_total — the total number. Paths and messages longer than 1000 characters are truncated with an ellipsis.
Error codes
HTTP |
| Meaning and what to do |
|---|---|---|
401 |
| No key, or the key is invalid, revoked or expired |
403 |
| Insufficient permissions; the reason is in |
403 |
| A condition or sort on a field you are not allowed to read |
404 |
| The resource does not exist or is not visible to you |
404 |
| The object does not exist or is not visible to you |
404 |
| The process does not exist |
405 |
| The method is not supported for this path |
409 |
| The object was changed after you read it: re-read and retry |
409 |
| The object is archived |
409 |
| The object type is archived |
409 |
| A relation prevents the action |
409 |
| A request with this |
409 |
| A published definition version cannot be changed — create a draft |
409 |
| The approval has already been decided |
413 |
| The body exceeds the limit |
422 |
| Invalid parameters; details are in |
422 |
| A structural limit is exceeded (number of fields, relations, items) |
422 |
| The same |
422 |
| The field is read-only |
422 |
| The field is not in the object's schema version |
422 |
| The status can only be changed by a transition |
422 |
| A type rule is violated |
422 |
| The transition is not available right now; reasons are in |
422 |
| The allowed number of relations is violated |
422 |
| The relation creates a cycle |
422 |
| The object is not suitable for this relation |
422 |
| The definition fails the publishing check |
422 |
| Unsupported time pattern in an expression |
422 |
| Too many related objects to check |
422 |
| The query is too expensive; the reason is in |
422 |
| The field index quota is used up |
422 |
| Fields of this type cannot be indexed |
422 |
| When publishing a status process, you did not specify where to move objects from removed statuses |
422 |
| The approval is not assigned to you |
422 |
| This automation run cannot be retried |
422 |
| An external event with the same key but different content |
426 |
| The client version in |
429 |
| The rate limit is exceeded; wait |
500 |
| Internal error; the change was rolled back |
503 |
| Temporarily unavailable; retry after |
Other details.reason values for 403: csrf and session_revoked apply to the browser session and the embed token; integrations do not encounter them.
Retries
Retry the request after 429, 503, 500 and network errors — for changes, with the same Idempotency-Key. After 409 OBJECT_VERSION_CONFLICT, re-read the object first. Do not retry unchanged requests that got 401, 403, 404 or 422.
Limits
What | Limit |
|---|---|
Requests per minute per workspace | 6000 |
Requests per minute per member (key) in a workspace | 1200 |
Requests per minute through the legacy gateway sensever.com/api/v1/flow (until 13.10.2026) | 120 |
Request body | 1 MB; 10 MB for bulk operations and import ( |
Fields in one change ( | 200 |
| 1 KB / 100 KB |
| 64 KB |
Items in a multi-value field | 1000 |
Checklist ( | 100 items of 1–500 characters; 100 operations in |
Tags ( | 20 tags of 1–50 characters |
Relations when creating an object | 100 |
Objects in a bulk request | 1000 |
| 200 |
| 500 |
Calendar downloads per subscription link | 60 per hour |
Query (Query AST) | 32 KB |
External event body | 256 KB |
Stored response for an | 64 KB |
Page size | 1–200 |
Per-minute request limits are defaults; the workspace owner can change them with quotas (PATCH /workspace). When a limit is exceeded, you get 429 RATE_LIMITED and a Retry-After header. Structural limits return 422 LIMIT_EXCEEDED with details.limit and details.actual.
All methods
The service endpoints GET /health/live and GET /health/ready respond without authorization.
Objects
Details: Flow API: objects, transitions and relations.
Method | Request |
|---|---|
Create an object |
|
Read, update |
|
Archive, restore |
|
Run a transition |
|
Available actions |
|
Run an object action |
|
History |
|
Relations |
|
Relations of many objects |
|
Checklist items |
|
Files |
|
Discussion in chat |
|
Mentions |
|
Subtasks, checklists and recurrence
Details: Flow API: subtasks, checklists and recurrence.
Method | Request |
|---|---|
Enable subtasks for a type |
|
Subtask counters |
|
Checklist items |
|
Object recurrence |
|
Which objects recur |
|
Time tracking
Details: Flow API: time tracking.
Method | Request |
|---|---|
Object time |
|
Time entries |
|
Timer |
|
Totals for a table column |
|
"Time" report |
|
Queries and search
Details: Flow API: query language and search.
Method | Request |
|---|---|
Query objects of a type |
|
Objects of all my workspaces (session only) |
|
Field index |
|
Full-text search language |
|
Personal lists, calendar and email
Session or embed token only. Details: Flow API: personal lists, calendar and email.
Method | Request |
|---|---|
"By section": my tasks across all workspaces |
|
"All objects" as a calendar and filter options |
|
Calendar subscription links |
|
Calendar via a subscription link (public) |
|
Email settings |
|
Types, fields, statuses and rules
Details: Flow API: types, fields, statuses and publishing.
Method | Request |
|---|---|
Object types |
|
Type presets |
|
Template as a file |
|
Fields and schema versions |
|
Migrating objects to the current schema |
|
Field tags |
|
Subtasks |
|
Relation types |
|
Status process |
|
Rules (constraints) |
|
Object actions |
|
Views, export, import, background operations
Details: Flow API: views, export, import and background operations.
Method | Request |
|---|---|
Views |
|
Export to CSV |
|
Uploading CSV for import |
|
Background operations |
|
Automations and reminders
Details: Flow API: automations, reminders and expressions.
Method | Request |
|---|---|
Automations |
|
Automation versions |
|
Run log |
|
Due date reminders |
|
Processes, approvals, external events
Details: Flow API: processes, approvals and external events.
Method | Request |
|---|---|
Processes |
|
Start and instances |
|
Approvals |
|
Approvals across all my workspaces (session only) |
|
External event |
|
Webhooks
Details: Flow API: webhooks.
Method | Request |
|---|---|
Subscriptions |
|
Deliveries, secret, test |
|
Reports and business calendar
Details: Flow API: reports, SLA and business calendar.
Method | Request |
|---|---|
Dashboard summaries |
|
Funnel and burndown |
|
Dashboards |
|
Summary across all my workspaces (session only) |
|
Time in status |
|
SLA |
|
Business calendar |
|
Workspace, access, notifications
Details: Flow API: workspace, access and notifications.
Method | Request |
|---|---|
Workspace |
|
Me and my workspaces (session only) |
|
Members |
|
Invitations |
|
My invitations (session only) |
|
Roles and permissions |
|
Teams |
|
Workspace keys |
|
My notifications |
|
Comentários