Flow API: query language and search

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

Оқуға 15 мин

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

POST /objects/query

A page of objects of one type matching a condition

All workspaces

POST /me/objects/query

Objects from all of the user's workspaces; browser session only

Field index

GET /fields/{id}/index

State of a field's index

Enable index

POST /fields/{id}/index

Build a field index in the background

Disable index

DELETE /fields/{id}/index

Delete a field index in the background

Search language

GET /search/settings

The workspace's full-text search language

Change search language

PUT /search/settings

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

type

string

Yes

Key or id of the object type. A query always covers one type

where

object or null

No

Condition, see below

sort

array or null

No

Sort keys. Default is created_at desc; id is always appended as the last key

page

object or null

No

size — from 1 to 200, default 50; cursor — the next_cursor of the previous page

select

array or null

No

Which fields to return in fields. System attributes are always returned

search

string, object or null

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"}}

system

What it is

id

Object ID

title

Title

state.id, state.key, state.category

Status: id, key, category (open, in_progress, done, cancelled)

owner_id

Assignee

created_at, updated_at

Creation and modification time

created_by

Who created it

archived

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"}}

op

Meaning

has

There is a related object matching where

has_none

No related object matches where

is_empty

There are no relations of this type

is_not_empty

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

eq, ne

Equal, not equal

"high"

in, nin

In, not in a list

["high", "critical"]

lt, lte, gt, gte

Less than, at most, greater than, at least

"2026-10-01"

between

Within a range

["2026-09-01", "2026-09-30"]

is_empty, is_not_empty

Empty, not empty

no value

contains

String contains a substring

"contract"

starts_with

String starts with

"INV-"

has_any

List contains at least one of the values

[{"actor": "me"}]

has_all

List contains all values

["urgent", "legal"]

has_open_items, no_open_items

Checklist has, has no unchecked items

no value

Which operators fit which field type:

Field type

Operators

string, text

eq, ne, in, nin, contains, starts_with, is_empty, is_not_empty

enum, principal

eq, ne, in, nin, is_empty, is_not_empty

number, integer, money, date, datetime

eq, ne, in, nin, lt, lte, gt, gte, between, is_empty, is_not_empty

boolean

eq, ne, is_empty, is_not_empty

multi_enum, multi_principal, tags

has_any, has_all, in (same as has_any), nin (none of the values), is_empty, is_not_empty

checklist

has_open_items, no_open_items, is_empty, is_not_empty

json, relation

Value conditions are not supported; relations have the relation predicate

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 is now, start_of_day (00:00 UTC today) or start_of_week (Monday 00:00 UTC); the offset is + or -, a number and a unit d (days), h (hours) or m (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_READABLE with details.field and details.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 and fields are 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. fields are keys of text fields, and title is the title; without fields, the search covers all text fields you are allowed to read. An explicitly listed field you cannot read gets 403 FIELD_NOT_READABLE.

  • search is combined with where using "and". The specified sort is kept (default created_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 — use where conditions for them.

  • The same search works on top of a saved view — the search field in POST /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.

details.reason

Limit

predicates

No more than 50 predicates per query

or_branches_per_level

No more than 10 or branches on one level

or_branches_total

No more than 30 or branches in total

logical_depth

No more than 5 levels of nested logical nodes

relation_filters

No more than 3 relation filters

relation_depth

A relation filter can be only one level deep

list_values

No more than 500 values in in or has_any

sort_keys

No more than 3 sort keys (plus id)

unindexed_predicates

No more than 5 conditions on unindexed fields; a type with more than a million objects needs at least one condition on an index

contains_unindexed

contains on an unindexed field only if the type has no more than 200,000 objects

sort_unindexed

Sorting by an unindexed field only if the type has no more than 50,000 objects

plan_cost

The database's cost estimate for the query exceeds the workspace threshold

statement_timeout

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}
}

filter field

Description

workspace_ids

Only these workspaces (ids from GET /me), up to 100

state_categories

Status categories: open, in_progress, done, cancelled

owner_user_id

Assignee: me, none (no assignee) or a Flow user id — user.id from GET /me, or the user_id of a member or person from GET /me/objects/filters. In each workspace, it is matched against that person's member record there

type_keys

Only types with these keys, up to 50. The same key in different workspaces counts as one type. Options are types from GET /me/objects/filters

title_contains

Case-insensitive title substring, up to 200 characters

search

Full-text search, like search in POST /objects/query, using each workspace's language

due

Due date from–to inclusive, by the type's due_date or due_at field

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:

reason

Meaning

workspace_limit

There are more workspaces than can be read at once — narrow workspace_ids

time_budget

The page ran out of time

error

An error in this workspace; the code is in error_code

not_available

The requested workspace is not among your active ones

workspace_suspended

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

Пікірлер

Авторлар