Flow API: views, export, import and background operations

SENSEVER

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

16 min bacaan

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

GET /object-types/{type}/views

Shared views and your personal ones

Create a view

POST /object-types/{type}/views

A new view owned by you

Read a view

GET /views/{id}

Query and settings, including for an archived view

Update a view

PATCH /views/{id}

Name, view type, query, settings, access

Archive a view

DELETE /views/{id}

Move the view to the archive

Run a view

POST /views/{id}/query

A page of objects or the board columns

Export a view

GET /views/{id}/export

CSV with the view's objects

Export a query

POST /objects/export

CSV with objects matching a condition

Upload a CSV

POST /import-files

File for import: columns and first rows

Read a file

GET /import-files/{id}

Columns and first rows of the uploaded file

Start an operation

POST /operations

Import, bulk changes, migrations

Operation state

GET /operations/{id}

Status and progress

Operation errors

GET /operations/{id}/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

Name, 1–200 characters

view_type

table, board, pipeline, calendar, timeline or list

query

Query: type, where, sort, page.size, select — no cursor. type is always the view's type

config

Display settings, up to 64 KB

visibility

private — only the owner sees it; shared — everyone allowed to read the type's views

position

Order in the list

owner_id

Owner — whoever created the view

The Flow interface shows the table, board, calendar and timeline.

config settings

Key

Used by

Description

columns

Table

Columns: a field key or a system column (id, title, state, owner_id, created_by, created_at, updated_at, $time_spent), or {"field": "…", "width": 140} with a width of 20–2000. Up to 100 columns. A relation field can also be a column — for example, subtasks shows the subtask count. $time_spent is the "Spent" column: running the view does not return its values; they come from POST /time/totals (see Flow API: time tracking)

group_by

Board, pipeline

Required for board and pipeline, forbidden for other view types: {"kind": "state"} — by status, or {"kind": "field", "field": "priority"} — by an enum list field

card

Board

Card: title and up to 20 fields

date_field

Calendar

A date or datetime field of the current schema used to place objects on days

start_field, end_field

Timeline

date or datetime fields of the current schema — the start and end of a bar. Optional: without them, the interface uses start_date (start_at) and due_date (due_at)

scale

Timeline

Scale: day, week or month

group

Timeline

Rows: none, owner, state or a field key of the type

dependency

Timeline

Key of a relation type from the type to itself, drawn as dependency arrows; without it, the interface uses the blocked_by relation

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

name

string

Yes

Name

view_type

string

Yes

View type

query

object

No

Query; query.type can be omitted

config

object

No

Display settings

visibility

string

No

Defaults to private

position

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

page

object

size (1–200) and cursor

group

string or null

The board column to page further

range

object or null

Calendar date range {from, to}

owner

string or null

Filter by assignee: a member id, me or none (no assignee)

where

object or null

A condition that replaces the view's query.where: this is how the interface applies board and calendar filters on top of a saved view. Validated the same way as where in POST /objects/query. Omitted — the view's condition; null — no condition

search

string or null

Full-text search on top of the condition, up to 200 characters, like search in POST /objects/query; applies in every board column. Empty or null — no search

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 empty column for objects with no value.

  • A column id is state:<status id>, value:<option> or empty.

  • One request loads up to 50 columns; the rest come with loaded: false. To load a column or its next page, pass group and page.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

query

object

Yes

type, where, sort — without page and select

columns

array

No

System columns (id, title, state, owner_id, created_by, created_at, updated_at, archived_at) and fields of the current schema, up to 200. An unknown column returns 422

header

string

No

labels (default) — field and option labels; keys — keys, handy for re-importing

locale

string

No

Language of the system column labels (Title, Status, Assignee…) with header=labels: en, de, es and other interface languages; defaults to ru. Field and option labels are the ones set in the workspace

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.csv

Content-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_EXCEEDED with details.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

file_id

Id of the uploaded file

type

Object type

header

true (default) — the first line contains column names and is not imported

mapping

Mapping [{column, field}]: column is a zero-based column number, field is a field key of the current schema or title

duplicates

{mode, key} — what to do with duplicates

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 the key field;

  • update — the single such object is updated with the row's non-empty cells; if there are several matches, the row fails with ambiguous_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

kind

string

Yes

Operation kind

params

object

Yes

Parameters for the kind

automation_mode

string

No

normal — automations fire as usual; low_priority — the operation's events are processed in a background queue; suppressed — automations don't fire (requires a separate permission; the action is logged)

Operation kinds

kind

Parameters

Progress

Error ref

import

see "CSV import"

total, processed, created, updated, unchanged, skipped, failed

Row number

bulk_create

type, items — 1 to 1000 objects {fields, title?, owner_id?}

total, processed, created, failed

Item number (7 digits)

bulk_update

items — 1 to 1000 {object_id, expected_version?, set?, unset?, title?, owner_id?}, or object_ids (1–1000) with shared set, unset, title, owner_id

total, processed, updated, unchanged, failed

Object id

bulk_archive

object_ids — 1 to 1000

total, processed, archived, unchanged, failed

Object id

bulk_transition

object_ids — 1 to 1000, to_state — status key, reason — a comment up to 1000 characters (optional)

total, processed, transitioned, unchanged, failed

Object id

lifecycle_migration

from_version_id, to_version_id, mapping

—

—

schema_migration

object_type_id, from_version_id, to_version_id, set ({key: {expr} or {value}}), unset, on_constraint_violation (skip)

—

—

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

status

Meaning

queued

Queued

running

Running

paused

Paused

succeeded

Completed; skipped items are counted in item_errors

failed

The operation as a whole failed; the reason is in error

cancelled

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

import, bulk_create

Create objects of the type; import in update mode also needs update

bulk_update

Update objects

bulk_archive

Archive objects

bulk_transition

Run the relevant transitions

lifecycle_migration, schema_migration

Manage the type's schema

automation_mode: suppressed

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

Komen

Pengarang