Flow API: views, export, import and background operations
A view is a saved selection of objects together with display settings: a table with columns, a board with columns by status, a calendar by a date field, or a timeline with bars from start to due date. Export downloads the objects of a view or a query as CSV. Import uploads a CSV file and creates or updates objects. Bulk changes and moving objects between versions run as background operations. This article covers all four mechanisms.
The API address, authorization and error format are described in Flow API: basics, and the condition language in Flow API: query language and search. For the same features in the interface, see Flow: table, board, calendar and filters and Flow: CSV import and export.
Methods
Method | Request | What it does |
|---|---|---|
Views of a type |
| Shared views and your personal ones |
Create a view |
| A new view owned by you |
Read a view |
| Query and settings, including for an archived view |
Update a view |
| Name, view type, query, settings, access |
Archive a view |
| Move the view to the archive |
Run a view |
| A page of objects or the board columns |
Export a view |
| CSV with the view's objects |
Export a query |
| CSV with objects matching a condition |
Upload a CSV |
| File for import: columns and first rows |
Read a file |
| Columns and first rows of the uploaded file |
Start an operation |
| Import, bulk changes, migrations |
Operation state |
| Status and progress |
Operation errors |
| Skipped rows and objects with reasons |
Views
The view object
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6a01",
"object_type_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f00",
"object_type": "task",
"name": "My urgent",
"view_type": "table",
"query": {
"type": "task",
"where": {"and": [
{"system": "owner_id", "op": "eq", "value": {"actor": "me"}},
{"field": "priority", "op": "in", "value": ["high", "critical"]}
]},
"sort": [{"field": "due_date", "dir": "asc"}],
"page": {"size": 50}
},
"config": {"columns": ["title", "state", {"field": "due_date", "width": 140}, "owner_id"]},
"owner_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"visibility": "private",
"position": 0,
"created_at": "2026-09-20T09:00:00.000000Z",
"updated_at": "2026-09-20T09:00:00.000000Z",
"archived_at": null
}Field | Description |
|---|---|
| Name, 1–200 characters |
|
|
| Query: |
| Display settings, up to 64 KB |
|
|
| Order in the list |
| Owner — whoever created the view |
The Flow interface shows the table, board, calendar and timeline.
config settings
Key | Used by | Description |
|---|---|---|
| Table | Columns: a field key or a system column ( |
| Board, | Required for |
| Board | Card: |
| Calendar | A |
| Timeline |
|
| Timeline | Scale: |
| Timeline | Rows: |
| Timeline | Key of a relation type from the type to itself, drawn as dependency arrows; without it, the interface uses the |
All other keys are stored as is — they are interface settings.
List, create, update
GET /object-types/{type}/views returns non-archived shared views and your personal ones, sorted by position, then name. You need permission to read the type's views.
POST /object-types/{type}/views:
{
"name": "Task board",
"view_type": "board",
"visibility": "shared",
"query": {"where": {"system": "state.category", "op": "ne", "value": "cancelled"}},
"config": {"group_by": {"kind": "state"}, "card": {"title": "title", "fields": ["owner_id", "due_date"]}}
}Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Name |
| string | Yes | View type |
| object | No | Query; |
| object | No | Display settings |
| string | No | Defaults to |
| integer | No | Defaults to 0 |
The query is validated as if you were running it: unknown fields and operators return 422 VALIDATION_FAILED (the path starts with query.), fields you can't read return 403 FIELD_NOT_READABLE, and a query that is too expensive returns 422 QUERY_TOO_EXPENSIVE. You need permission to manage the type's views.
PATCH /views/{id} changes the properties you pass; query and config are replaced as a whole. If your permission to manage views covers only your own, you can change only your own. Other people's personal views return 404.
DELETE /views/{id} archives the view (archived_at); repeating the call is safe. An archived view can be read through GET /views/{id} but cannot be run.
Create, update and archive support Prefer: return=minimal — see "Compact responses" in Flow API: types, fields, statuses and publishing.
Running a view
POST /views/{id}/query runs the view's query with your permissions:
Field | Type | Description |
|---|---|---|
| object |
|
| string or | The board column to page further |
| object or | Calendar date range |
| string or | Filter by assignee: a member id, |
| object or | A condition that replaces the view's |
| string or | Full-text search on top of the condition, up to 200 characters, like |
For a table or calendar, the response is a single page:
{
"view_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6a01",
"view_type": "table",
"items": [],
"page": {"size": 50, "next_cursor": null},
"meta": {"unindexed_fields": []}
}For a board (board, pipeline), there is a page per column:
{
"view_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6a02",
"view_type": "board",
"group_by": {"kind": "state"},
"groups": [
{
"id": "state:0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71",
"label": "In progress",
"state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71", "key": "in_progress", "category": "in_progress"},
"value": null,
"in_current_version": true,
"loaded": true,
"items": [],
"page": {"size": 50, "next_cursor": null}
}
],
"meta": {"unindexed_fields": []}
}Status columns are the statuses of the current process version in order, followed by statuses of old versions as long as they still hold objects (
in_current_version: false). Objects from different process versions land in the same column by the status's permanent id.Field columns are the field's options plus an
emptycolumn for objects with no value.A column
idisstate:<status id>,value:<option>orempty.One request loads up to 50 columns; the rest come with
loaded: false. To load a column or its next page, passgroupandpage.cursor.
range is a half-open range [from, to) on the config.date_field field:
{"range": {"from": "2026-08-31", "to": "2026-10-05"}, "page": {"size": 200}}For a date field, both bounds are YYYY-MM-DD dates: an object shows on its own day in any time zone. For datetime, a bound is a date (00:00 UTC) or an RFC 3339 time with an offset; pass the boundaries of the user's days. If the view has no suitable date field, range returns 422 with the code no_date_field. Board grouping, range and owner apply to the condition from where the same way as to the view's condition. The range, owner, where and search are part of the cursor: pass the same values for the next page.
Example — a view's board filtered by priority and a search:
{
"where": {"and": [
{"system": "state.category", "op": "ne", "value": "cancelled"},
{"field": "priority", "op": "in", "value": ["high", "critical"]}
]},
"search": "contract",
"page": {"size": 50}
}Running a view only reads data and needs no Idempotency-Key, but the method is POST, so a "Read-only" key can't call it. An archived view returns 404.
CSV export
GET /views/{id}/export downloads a view's objects:
curl -s -o tasks.csv "https://flow.sensever.com/v1/views/$VIEW_ID/export?header=labels&locale=en" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID"POST /objects/export downloads objects matching a query:
{
"query": {
"type": "task",
"where": {"system": "state.category", "op": "eq", "value": "done"},
"sort": [{"system": "updated_at", "dir": "desc"}]
},
"columns": ["id", "title", "state", "owner_id", "due_date"],
"header": "labels",
"locale": "en"
}Field | Type | Required | Description |
|---|---|---|---|
| object | Yes |
|
| array | No | System columns ( |
| string | No |
|
| string | No | Language of the system column labels ( |
GET /views/{id}/export takes the same header and locale as query string parameters.
File format:
UTF-8 with BOM,
,as the delimiter, CRLF line endings — opens in Excel;view columns come from
config.columns; otherwise: id, title, status, fields of the current schema, assignee, creation and update times;a board is exported as a whole, without splitting into columns;
columns for fields you can't read are not exported; a filter on such a field returns
403 FIELD_NOT_READABLE;text starting with
=,+,-or@gets a leading'— protection against spreadsheet formulas;no more than 100,000 rows (response header
X-Flow-Export-Max-Rows). A file with exactly that many rows may have been truncated — narrow the condition.
Errors are detected before the file starts and come as regular JSON. Export only reads data.
CSV import
Import takes three steps: upload the file, review the columns, start the operation.
1. Uploading the file
POST /import-files — the request body is the file itself (not multipart), up to 10 MB:
curl -s https://flow.sensever.com/v1/import-files?name=deals.csv \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: text/csv" \
--data-binary @deals.csvContent-Type is text/csv, text/plain, text/tab-separated-values, application/vnd.ms-excel or application/octet-stream. The name parameter is the original file name.
The file is parsed right away:
encoding — UTF-8 (the BOM is removed), UTF-16 with BOM, or Windows-1251 if the bytes are not UTF-8;
delimiter —
,,;or tab: whichever occurs most often in the first line;limits — 100,000 rows, 200 columns, 100 KB per cell (
422 LIMIT_EXCEEDEDwithdetails.limit,details.actual,details.row).
Response:
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c30",
"name": "deals.csv",
"size_bytes": 18234,
"encoding": "windows-1251",
"delimiter": "semicolon",
"row_count": 241,
"columns": ["Name", "Amount", "Close date", "Stage"],
"sample": [
{"row": 2, "cells": ["Equipment delivery", "150 000,00", "30.09.2026", "Negotiation"]}
],
"created_at": "2026-09-25T08:00:00.000000Z",
"expires_at": "2026-10-02T08:00:00.000000Z"
}columns is the first line of the file, and sample holds up to 5 following rows with their numbers. The file is visible only to whoever uploaded it and is kept for 7 days; starting an import extends that period. GET /import-files/{id} returns the same data again.
2. Starting the import
POST /v1/operations
Idempotency-Key: import-deals-2026-09-25{
"kind": "import",
"params": {
"file_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c30",
"type": "deal",
"header": true,
"mapping": [
{"column": 0, "field": "title"},
{"column": 1, "field": "amount"},
{"column": 2, "field": "expected_close_date"}
],
"duplicates": {"mode": "update", "key": "title"}
}
}Parameter | Description |
|---|---|
| Id of the uploaded file |
| Object type |
|
|
| Mapping |
|
|
duplicates.mode modes:
create— every row creates an object;skip— a row is skipped if there is a visible non-archived object with the same value in thekeyfield;update— the single such object is updated with the row's non-empty cells; if there are several matches, the row fails withambiguous_key.
Empty cells are not filled in on create and do not change values on update. Values are converted by field type: numbers with a decimal comma, DD.MM.YYYY dates, list options by label, yes/no, lists separated by ;. Invalid values become row errors; the remaining rows are applied.
You need permission to create objects of the type, and in update mode also to update them.
3. Result
The response to starting an import is 202:
{"operation_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c40", "status_url": "/v1/operations/0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c40"}Poll GET /operations/{id} until status becomes final. Import progress is {total, processed, created, updated, unchanged, skipped, failed}. Row errors are in GET /operations/{id}/errors, where ref is the file's row number as 7 digits with leading zeros:
{
"items": [
{"ref": "0000017", "error": {"code": "VALIDATION_FAILED", "message": "…", "details": {}}, "created_at": "2026-09-25T08:01:10.000000Z"}
],
"page": {"size": 50, "next_cursor": null}
}Background operations
POST /operations starts an operation and immediately responds 202 with operation_id and status_url. Idempotency-Key is required, the body can be up to 10 MB, and params up to 256 KB.
Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Operation kind |
| object | Yes | Parameters for the kind |
| string | No |
|
Operation kinds
| Parameters | Progress | Error |
|---|---|---|---|
| see "CSV import" |
| Row number |
|
|
| Item number (7 digits) |
|
|
| Object id |
|
|
| Object id |
|
|
| Object id |
|
| — | — |
|
| — | — |
In bulk_update, without expected_version the object's current version is used; owner_id changes the assignee, as in PATCH /objects/{id}.
bulk_transition moves objects to the to_state status even if they are in different statuses. For each object, Flow takes the transitions of its process version that lead from the current status to to_state, in graph order, and runs the first allowed one — as a regular transition, with all checks but without form fields. An object already in to_state counts as unchanged. If there is no suitable transition or all are rejected, the item error is TRANSITION_NOT_ALLOWED with details.reasons (with no suitable transition the reason is TRANSITION_NOT_FROM_STATE; a transition with a required empty form field gets REQUIRED_FIELD_MISSING).
Other kinds return 422 VALIDATION_FAILED with the code operation_kind_unsupported. The cascade_archive, field_backfill, field_index_drop and reminder_backfill kinds are started by the server itself: when archiving with a large cascade, when turning a field index on or off, and when configuring reminders. They are also visible through GET /operations/{id}.
Example — lower the priority of two tasks:
{
"kind": "bulk_update",
"params": {
"object_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90"],
"set": {"priority": "low"}
},
"automation_mode": "low_priority"
}Example — close tasks selected on the board:
{
"kind": "bulk_transition",
"params": {
"object_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90"],
"to_state": "done",
"reason": "Closed by a bulk action"
}
}Each item goes through the same commands as a single request: value validation, your permissions, constraints, the log and events. Retrying a batch after a handler failure never applies an item twice. Failed items are skipped, and the rest are applied.
Operation state
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c40",
"kind": "bulk_update",
"status": "succeeded",
"automation_mode": "low_priority",
"params": {"object_ids": ["…"], "set": {"priority": "low"}},
"progress": {"total": 2, "processed": 2, "updated": 2, "unchanged": 0, "failed": 0},
"item_errors": 0,
"error": null,
"created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"created_at": "2026-09-25T08:00:00.000000Z",
"started_at": "2026-09-25T08:00:01.000000Z",
"finished_at": "2026-09-25T08:00:02.000000Z"
}
| Meaning |
|---|---|
| Queued |
| Running |
| Paused |
| Completed; skipped items are counted in |
| The operation as a whole failed; the reason is in |
| Cancelled |
An operation is visible to its author and to those who can manage the workspace; everyone else gets 404 NOT_FOUND.
Permissions
Operation | Required permission |
|---|---|
| Create objects of the type; |
| Update objects |
| Archive objects |
| Run the relevant transitions |
| Manage the type's schema |
| Disable automations in the workspace |
An API key with restricted scopes is checked when the operation starts: import and bulk_create require object:create, bulk_update requires object:update, bulk_archive requires object:archive, and bulk_transition requires transition:execute. The items themselves run with the permissions of whoever started the operation.
What's next
Flow API: objects, transitions and relations — changing objects one at a time.
Flow API: webhooks — events about created and changed objects.
댓글