Filters — Overview
1.
GET/POST/PUT /v1/flows/{id}/filters) — manage a pre-configured view of a flow's kanban board, persisted for reuse in the interface (sorting, field projection and conditions). Each user has at most one saved filter per flow, always tied to the authenticated user.2.
POST /v1/filters/flows/{flowId}/search and POST /v1/filters/search) — run a one-off query using a condition language (DSL), returning the matching cards directly. The first scopes the search to a single flow; the second spans every flow accessible to the authenticated user.A saved filter is configuration; a search is a query. Saving a filter does not run any search, and searching cards does not persist anything.
Endpoints in this domain
| Method | Path | Description |
|---|---|---|
GET | /v1/flows/{id}/filters | Lists the flow's saved filters for the authenticated user |
POST | /v1/flows/{id}/filters | Creates the authenticated user's saved filter for the flow |
PUT | /v1/flows/{id}/filters | Updates the authenticated user's saved filter for the flow |
POST | /v1/filters/flows/{flowId}/search | Searches cards within a single flow |
POST | /v1/filters/search | Searches cards across every flow accessible to the user |
Naming note: the flow parameter varies across paths in this domain. In saved filters, it is {id}; in the per-flow search, it is{flowId}. The global search has no flow parameter in the path at all, since the query spans multiple flows.
Saved filters: ownership rules
userId field must never be sent in the POST or PUT body. Sending it returns a 400 error.POST) for the same pair returns a 422 error, stating that the filter already exists — in that case, use the update operation (PUT) instead of creating again.PUT) fully replaces the previous configuration — sorting, limit, field projection and conditions.Card search: envelope rules
page and pageSize fields are not accepted by either search endpoint and return a 400 error if present in the body.order (asc or desc), orderBy (sort path, non-empty), fields (non-empty list of {path} projections) and conditions (non-empty list of condition nodes).conditions is either a group (scope, logic — AND or OR — and a list of subconditions) or a leaf (scope, path and, optionally, operator and value). The scope field — any, all or sum — is required on every node, group or leaf, and defines the aggregation semantics over collections.conditions and fields.Important behaviors
conditions is a single group (logic plus a list of subconditions); in a search, conditions is a list of nodes at the root, each of which can be a group or a leaf.userId) and flow identifier (flowId) present in the response when reading a saved filter are always denormalized by the API — never set by the client.POST method, even though the operation is a read — the request body carries the condition envelope, which would not normally fit in a query string.Modificado em 2026-07-28 20:38:32