Flow API: query language and search
Object lists in Flow are read with a single method, POST /objects/query. A query is described as a JSON tree of conditions (Query AST): which type, which conditions, how to sort, and how many objects per page. The server validates the query against the type's schema and your permissions, turns it into parameterized SQL and returns a page of objects. Views, export, webhooks and automations use the same language.
The API base URL, authorization and error format are described in Flow API: basics. How the same filters look in the interface is shown in Flow: table, board, calendar and filters.
Methods
Method | Request | What it does |
|---|---|---|
Query objects |
| A page of objects of one type matching a condition |
All workspaces |
| Objects from all of the user's workspaces; browser session only |
Field index |
| State of a field's index |
Enable index |
| Build a field index in the background |
Disable index |
| Delete a field index in the background |
Search language |
| The workspace's full-text search language |
Change search language |
| Change the language and reindex objects |
First query
Open high-priority tasks due within the next week, most urgent first:
curl -s https://flow.sensever.com/v1/objects/query \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"type": "task",
"where": {
"and": [
{"field": "priority", "op": "in", "value": ["high", "critical"]},
{"field": "due_date", "op": "lt", "value": {"relative": "now+7d"}},
{"system": "state.category", "op": "ne", "value": "done"}
]
},
"sort": [{"field": "due_date", "dir": "asc"}],
"page": {"size": 50},
"select": ["priority", "due_date"]
}'Response:
{
"items": [
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"type": "task",
"title": "Prepare the contract",
"version": 4,
"state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71", "key": "in_progress", "category": "in_progress", "entered_at": "2026-09-20T08:00:00.000000Z"},
"owner_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"schema_version": 2,
"lifecycle_version": 1,
"fields": {"priority": "high", "due_date": "2026-09-27"},
"created_at": "2026-09-19T12:00:00.000000Z",
"updated_at": "2026-09-20T08:00:00.000000Z",
"archived_at": null
}
],
"page": {"size": 50, "next_cursor": "eyJrIjpb…"},
"meta": {"unindexed_fields": ["priority"]}
}The query only reads data: no Idempotency-Key is needed, and a read-only key can call this method.
Request body
Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Key or id of the object type. A query always covers one type |
| object or | No | Condition, see below |
| array or | No | Sort keys. Default is |
| object or | No |
|
| array or | No | Which fields to return in |
| string, object or | No | Full-text search, see "Text search" |
The body can be at most 32 KB (422 LIMIT_EXCEEDED, details.reason = query_ast_bytes).
Conditions
A condition is a tree of logical nodes and predicates.
Logical nodes
{"and": [condition, …]}— all conditions are met;{"or": [condition, …]}— at least one is met.
Nodes can be nested up to five levels deep. There is no separate "not" node: use the operators ne, nin, is_empty and has_none.
Field predicate
{"field": "priority", "op": "eq", "value": "high"}field is the key of a type field.
System attribute predicate
{"system": "owner_id", "op": "eq", "value": {"actor": "me"}}
| What it is |
|---|---|
| Object ID |
| Title |
| Status: id, key, category ( |
| Assignee |
| Creation and modification time |
| Who created it |
| Whether the object is archived |
Archived objects are excluded from results unless the condition mentions archived. For example, {"system": "archived", "op": "eq", "value": true} returns only archived objects.
Filtering by status category is more convenient than by key: status keys differ between types, while the done category means "completed" everywhere.
Relation predicate
{"relation": "project", "op": "has", "where": {"system": "id", "op": "eq", "value": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b10"}}
| Meaning |
|---|---|
| There is a related object matching |
| No related object matches |
| There are no relations of this type |
| There is at least one relation |
Inside the relation's where, conditions apply to the related object. Depth is one level: a relation filter inside a relation filter is not supported.
Operators
Operator | Purpose | Example value |
|---|---|---|
| Equal, not equal |
|
| In, not in a list |
|
| Less than, at most, greater than, at least |
|
| Within a range |
|
| Empty, not empty | no |
| String contains a substring |
|
| String starts with |
|
| List contains at least one of the values |
|
| List contains all values |
|
| Checklist has, has no unchecked items | no |
Which operators fit which field type:
Field type | Operators |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Value conditions are not supported; relations have the |
contains and starts_with are case-insensitive. Money is compared by amount; the currency is ignored. Tags in a condition are compared exactly as written, case-sensitively. For lists and checklists, is_empty means an empty list or no value. You cannot sort by list fields, checklists, json or relations. The server checks that the operator fits the field type and that the value has the right shape; an error returns 422 VALIDATION_FAILED with the path inside the query in details.fields[].field, for example where.and[2].value.
null is not allowed as a value — use is_empty for empty values. If an object's field is not filled in, eq, in and comparisons evaluate to false, while ne, nin and is_empty evaluate to true.
Relative dates and "me"
Instead of a specific value, you can pass:
{"relative": "now+7d"}— a time relative to the moment of the request. The base isnow,start_of_day(00:00 UTC today) orstart_of_week(Monday 00:00 UTC); the offset is+or-, a number and a unitd(days),h(hours) orm(minutes):now-30m,start_of_day+1d,start_of_week;{"actor": "me"}— whoever runs the query. Works for the assignee, the creator and member fields.
Dates in comparisons are YYYY-MM-DD (00:00 UTC) or an RFC 3339 time with an offset.
Example — my tasks and tasks I'm watching:
{
"or": [
{"system": "owner_id", "op": "eq", "value": {"actor": "me"}},
{"field": "watchers", "op": "has_any", "value": [{"actor": "me"}]}
]
}Sorting and pages
A sort key is {"field": "due_date", "dir": "asc"} or {"system": "updated_at", "dir": "desc"}, with exactly one of field and system. dir is asc (default) or desc. Empty values come last in both directions.
Pages use cursors. The response contains page.next_cursor; to get the next page, repeat the same query with "page": {"cursor": "<next_cursor>"}. null means the last page. A cursor is bound to its query: someone else's cursor or a cursor from a different query (another type, condition, sort or search) gets 422 VALIDATION_FAILED on page.cursor. There are no page numbers or total counts — use reports for counting, see Flow API: reports, SLA and business calendar.
async function* allObjects(query) {
let cursor = null;
do {
const res = await fetch('https://flow.sensever.com/v1/objects/query', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SENSEVER_API_KEY}`,
'X-Workspace-Id': process.env.WORKSPACE_ID,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ...query, page: { size: 200, cursor } }),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const data = await res.json();
yield* data.items;
cursor = data.page.next_cursor;
} while (cursor);
}Permissions in queries
If you are allowed to read only your own objects or your team's objects, that restriction is added to the query before your conditions.
A filter or sort on a field you are not allowed to read gets
403 FIELD_NOT_READABLEwithdetails.fieldanddetails.path. The error comes before any objects are read: the server does not silently drop such a condition, so that the number of results cannot reveal hidden data.Fields you have no permission to read are absent from the response.
For each object on a page,
version, the status andfieldsare read in one query and reflect the same moment, even if the object is being changed during the query. The query condition, however, is checked slightly before the page is read: an object changed at exactly that moment may arrive with new values that no longer match the condition.
Text search
The search field looks for words in the title and text fields (string, text):
{"type": "deal", "search": "invoice supplier"}or with a choice of fields:
{"type": "deal", "search": {"text": "invoice supplier", "fields": ["title", "notes"]}}Each word must appear as the beginning of a word in the title or in one of the fields. Words are normalized according to the workspace search language.
The text is 1 to 200 characters.
fieldsare keys of text fields, andtitleis the title; withoutfields, the search covers all text fields you are allowed to read. An explicitly listed field you cannot read gets403 FIELD_NOT_READABLE.searchis combined withwhereusing "and". The specified sort is kept (defaultcreated_at desc), and the search is part of the cursor.The index is updated in the background after an object changes, usually within a second. If an object is changed several times in a row, index updates run in sequence, and the index ends up with the object's latest state.
Tags (
tags), list options and checklists are not part of full-text search — usewhereconditions for them.The same search works on top of a saved view — the
searchfield inPOST /views/{id}/query, see Flow API: views, export, import and background operations.
Search language
GET /search/settings returns the current language and the list of available ones:
{"language": "russian", "languages": ["simple", "russian", "english", "german", "french", "spanish", "italian", "portuguese", "dutch", "swedish", "norwegian", "danish", "finnish", "turkish"]}simple ignores word forms: words match only as prefixes. With a language (for example russian), search finds different forms of a word. Any member can read this setting.
PUT /search/settings with {"language": "russian"} changes the language; it requires the permission to manage the workspace. The response contains reindex: true if the language changed: objects are reindexed in the background, and until that finishes, search finds only the objects already reindexed.
Query cost
The server rejects queries that are too expensive: 422 QUERY_TOO_EXPENSIVE with details.reason, details.limit and, if known, details.actual.
| Limit |
|---|---|
| No more than 50 predicates per query |
| No more than 10 |
| No more than 30 |
| No more than 5 levels of nested logical nodes |
| No more than 3 relation filters |
| A relation filter can be only one level deep |
| No more than 500 values in |
| No more than 3 sort keys (plus |
| No more than 5 conditions on unindexed fields; a type with more than a million objects needs at least one condition on an index |
|
|
| Sorting by an unindexed field only if the type has no more than 50,000 objects |
| The database's cost estimate for the query exceeds the workspace threshold |
| The query did not finish within the execution time limit |
What to do: simplify the condition, add a filter on a system attribute or an indexed field, or enable an index on the field you need.
Field indexes
System attributes (state, owner_id, creation and modification dates) are always indexed. Conditions on regular unindexed fields are slower, and such fields are listed in the response in meta.unindexed_fields — a hint about which field is worth indexing.
GET /fields/{id}/index returns the state of a field's index (the field id comes from the type's schema):
{
"field_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f01",
"object_type_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f00",
"key": "priority",
"data_type": "enum",
"index_policy": "indexed",
"status": "ready",
"total_objects": 1840,
"processed_objects": 1840,
"error": null,
"started_at": "2026-09-20T09:00:00.000000Z",
"completed_at": "2026-09-20T09:00:04.000000Z",
"operation_id": null
}status is backfilling (being built), ready, failed, dropping (being deleted) or null if there is no index.
POST /fields/{id}/index enables an index: the response is 202 with operation — the background backfill operation, whose progress is visible in GET /operations/{id}. If the index is already being built or is ready, you get 200 and operation: null. Errors: 422 FIELD_TYPE_NOT_INDEXABLE (text, json, relation and checklist fields cannot be indexed; tags can), 422 INDEX_QUOTA_EXCEEDED (with an estimate in details), 422 VALIDATION_FAILED (index_dropping, field_archived).
DELETE /fields/{id}/index disables the index and deletes it in the background (202), or responds 200 if there is nothing to delete.
Both methods require the permission to manage the type's schema. By default, a type can have up to 20 indexed fields and a workspace up to 200.
All workspaces
POST /me/objects/query returns objects from all workspaces where the person is an active member. This is the "All workspaces" mode of the Flow interface.
The method works only with a person's browser session or a Sensever embed token. An API key gets 401: a key always works in the workspaces specified in it, not in all of the person's workspaces. Integrations iterate over workspaces themselves, using POST /objects/query with the appropriate X-Workspace-Id.
{
"filter": {
"state_categories": ["open", "in_progress"],
"owner_user_id": "me",
"due": {"from": "2026-09-25", "to": "2026-09-30"}
},
"sort": {"by": "updated_at", "dir": "desc"},
"page": {"size": 50}
}
| Description |
|---|---|
| Only these workspaces (ids from |
| Status categories: |
| Assignee: |
| Only types with these keys, up to 50. The same key in different workspaces counts as one type. Options are |
| Case-insensitive title substring, up to 200 characters |
| Full-text search, like |
| Due date |
sort.by is updated_at (default) or created_at; page.size is from 1 to 100. Regular permissions and cost limits apply in each workspace.
A response item is a short summary of an object: id, workspace (id, name, is_system — the personal Main workspace), type (id, key, name), title, state, owner, due, version, created_at, updated_at. owner contains principal_id, user_id, name and picture_url (the photo from the Sensever account, or null — then show initials); user_id and name are null if you are not allowed to read the member list in that workspace. To open the full object, request GET /objects/{id} with its workspace's X-Workspace-Id.
One request reads at most 50 workspaces, and each page has a time budget. Workspaces that were not read are listed in meta.skipped_workspaces with a reason:
| Meaning |
|---|---|
| There are more workspaces than can be read at once — narrow |
| The page ran out of time |
| An error in this workspace; the code is in |
| The requested workspace is not among your active ones |
| The workspace is suspended |
For the first three reasons, meta.partial is true: the page may be missing objects from those workspaces. meta.workspaces_scanned is the number of workspaces read.
The same mode applies to GET /me/approvals — approvals across all workspaces (see Flow API: processes, approvals and external events), POST /me/reports/summary — the summary report (see Flow API: reports, SLA and business calendar), as well as POST /me/objects/calendar — "All objects" as a calendar, GET /me/objects/filters — options for the "Type" and "Assignee" filters, and GET /me/tasks — "By section" (see Flow API: personal lists, calendar and email). They report skipped workspaces the same way.
What's next
Flow API: objects, transitions and relations — what to do with the objects you find.
Flow API: views, export, import and background operations — saved queries, boards, calendars and CSV export.
Komentar