Flow API: subtasks, checklists and recurrence

SENSEVER

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

15 хв читання

Flow API: subtasks, checklists and recurrence

This article covers the methods that task workflows are built from: subtasks and "3/5" counters, batch reading of relations, operations on checklist items, tag suggestions, and recurring tasks. All of this works on objects of any type, not just tasks.

General rules — base URL, keys, the X-Workspace-Id and Idempotency-Key headers, the error format — are in Flow API: basics. For how this looks in the interface, see Flow: subtasks, checklists and tags and Flow: recurring tasks.

Methods

Method

Request

Permission

flw_… key scope

Enable subtasks for a type

POST /object-types/{type}/subtasks

schema.manage

schema:manage

Subtask counters for many objects

POST /objects/subtask-progress

object.read

object:read

Relations of many objects

POST /objects/relations

object.read

object:read

Checklist item operations

POST /objects/{id}/checklists/{field}

object.update and field.update

object:update, field:update

Tags already used in a field

GET /object-types/{type}/fields/{field}/tags

object.read and field.read

object:read, field:read

An object's recurrence series

GET /objects/{id}/recurrence

object.read

object:read

Make an object recur

PUT /objects/{id}/recurrence

object.update

object:update

Stop recurrence

DELETE /objects/{id}/recurrence

object.update

object:update

Next dates of a rule

POST /objects/{id}/recurrence/preview

object.read

object:read

Which objects recur

POST /recurrence/lookup

object.read

object:read

Paths are relative to https://flow.sensever.com/v1. {type} is a type key or id. All methods work within one workspace: with a session and X-Workspace-Id, with a Sensever platform key, or with a flw_… workspace key. The old gateway https://sensever.com/api/v1/flow (shut down on 13.10.2026) doesn't pass these methods through; https://api.sensever.com/v1/flow does.

The methods POST /objects/subtask-progress, POST /objects/relations, POST /objects/{id}/recurrence/preview and POST /recurrence/lookup only read data, so they don't use Idempotency-Key. But they're POST, so a "Read-only" platform key gets 403 with details.reason = read_only_key on them — you need a "Read and write" key. Modifying methods accept an optional Idempotency-Key.

Subtasks

A subtask is an object of the same type, linked to its parent by a many-to-one relation from the type to itself. Each type has its own subtask relation; if a type has several such relations, the oldest one counts as subtasks.

Enable subtasks

POST /object-types/{type}/subtasks does the same as the "Enable subtasks" button in type settings. In one request, Flow:

  1. creates a relation from the type to itself: many-to-one, no cycles, unlinked when the parent is archived (on_delete: unlink); the key is <type>_parent, for example task_parent;

  2. adds the fields "Parent task" (parent, the subtask side) and "Subtasks" (subtasks, the parent side). A taken key gets a suffix _2, _3…;

  3. if the type has no schema draft, publishes a new schema version right away, and objects move to it as usual. If there's a draft, the fields are added to it, and an administrator publishes it (draft: true);

  4. if the type has a status process and the fields are published, creates the parent_open_subtasks restriction: a parent can't move to a status in the done category while it has subtasks not in done and not in cancelled. Such a transition is rejected with 422 CONSTRAINT_VIOLATION. The restriction can be turned off like any other.

The body is optional: {"locale": "en"} sets the language for the names of the relation, fields and restriction (the same 22 languages as POST /workspaces), default ru.

curl -X POST https://flow.sensever.com/v1/object-types/task/subtasks \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"locale": "en"}'

Response 200:

{
  "created": true,
  "relation_type": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f01", "key": "task_parent", "system_key": null, "name": "Parent task", "inverse_name": "Subtasks", "cardinality": "many_to_one", "on_delete": "unlink", "is_acyclic": true},
  "parent_field": "parent",
  "children_field": "subtasks",
  "draft": false,
  "schema_version": 4,
  "constraint": "parent_open_subtasks"
}

relation_type also includes the other relation type fields (from_type_id, to_type_id, version_bump, archived, created_at). If the type already has a subtask relation, nothing changes: created: false, so repeating the request is safe. constraint is null if the type has no status process or the fields are still in a draft.

Errors: type not found — 404 NOT_FOUND; type archived — 409 OBJECT_TYPE_ARCHIVED; no schema.manage — 403 PERMISSION_DENIED.

Making a task a subtask is an ordinary relation, with the subtask on the from side and the parent on the to side: POST /objects/{subtask id}/relations/task_parent with {"object_id": "<parent id>"}, or on creation "relations": [{"relation": "task_parent", "object_id": "<parent id>", "side": "from"}]. To read subtasks, use GET /objects/{parent id}/relations/task_parent?direction=incoming. The relation key in the path is relation_type.key from the response, not the field key. How relations work is covered in Flow API: objects, transitions and relations.

"3/5" counters

POST /objects/subtask-progress returns how many subtasks are closed and how many there are in total, for 1–200 objects at once (for boards and tables).

{"object_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71"]}
{
  "items": {
    "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70": {"relation": "task_parent", "done": 3, "total": 5}
  }
}
  • Only subtasks you can read (taking own and team scopes into account) and that aren't archived are counted. Closed means in a status of the done or cancelled category.

  • Objects that don't exist, that you can't read, or whose type has no subtask relation are absent from items. An object without subtasks comes back with done: 0 and total: 0.

  • More than 200 ids returns 422 LIMIT_EXCEEDED; a non-UUID id returns 422 VALIDATION_FAILED on object_ids[i].

Relations of many objects

POST /objects/relations reads relations for many objects at once — for example, for all rows of a timeline: up to 500 object_ids, up to 5 relations in relations ({"key": "…", "direction": "outgoing" | "incoming"}), up to limit related objects per pair (1–50, default 20; more: true means there are more). Invisible and foreign objects are skipped, and empty sets aren't returned; an unknown relation returns 404 NOT_FOUND, more than 500 ids returns 422 LIMIT_EXCEEDED. A request and response example is in Flow API: objects, transitions and relations.

Checklists

POST /objects/{id}/checklists/{field} changes individual items of a checklist field without rewriting the whole list. Items are addressed by a permanent id, so two people checking different items at the same time don't interfere with each other.

Field

Description

expected_version

The object version you saw, an integer ≥ 1. Required

ops

1–100 operations, in order. Required

op

Parameters

What it does

add

text (1–500 characters), optional done, your own id (UUID), after

A new item after the after item; after: null puts it first; without after it goes to the end

check

id, done

Check or uncheck. The server records who checked it and when (done_by, done_at)

rename

id, text

New item text

remove

id

Delete the item

move

id, after

Move the item after after; null moves it to the top

curl -X POST https://flow.sensever.com/v1/objects/$OBJECT_ID/checklists/checklist \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Idempotency-Key: checklist-7f3a-31" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 31,
    "ops": [
      {"op": "check", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e11", "done": true},
      {"op": "add", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e12", "text": "Get a signature"}
    ]
  }'

Response 200 is the object after the change, as with PATCH /objects/{id}.

  • Version. If the object changed after expected_version, the operations are still applied — unless an affected item itself changed after that version or was deleted. In that case you get 409 OBJECT_VERSION_CONFLICT with details.reason item_changed or item_removed and details.item_id: reread the object and try again.

  • Repeats. An add with an existing id, a remove of a missing item, and an operation whose result is already in place change nothing. So your own id in add makes the request safe to repeat even without Idempotency-Key.

  • Limits. At most 100 operations per request (422 LIMIT_EXCEEDED) and 100 items in a list; item text is 1–500 characters.

  • Errors. Object not found or you can't read it — 404 OBJECT_NOT_FOUND; object archived — 409 OBJECT_ARCHIVED; field not in the object's schema — 422 FIELD_NOT_IN_SCHEMA_VERSION; field isn't a checklist — 422 VALIDATION_FAILED with code not_a_checklist; no permission to change the object or field — 403 PERMISSION_DENIED. Read-only fields, restrictions, history and events work as with PATCH /objects/{id} with the new list in set.

The checklist value format and writing the whole list via PATCH /objects/{id} are described in Flow API: objects, transitions and relations. In automation expressions, a checklist is a summary: data.checklist.open > 0, see Flow API: automations, reminders and expressions.

Tags

The value of a tags field is a list of strings: up to 20 tags (or fewer if max_items is set in the field settings), each 1–50 characters. Leading and trailing spaces are trimmed, inner spaces are collapsed to one, empty tags are skipped, and case-insensitive duplicates are dropped — the first spelling stays. Tags are written with an ordinary PATCH /objects/{id}.

GET /object-types/{type}/fields/{field}/tags returns the tags already set on objects of the type, for suggestions while typing. The most frequent come first.

Parameter

Description

q

Only tags containing this text, case-insensitive; up to 50 characters

limit

1–100, default 20

curl "https://flow.sensever.com/v1/object-types/task/fields/tags/tags?q=cli&limit=10" \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"
{"items": [{"tag": "client", "count": 42}, {"tag": "key client", "count": 7}]}

count is the number of objects with this tag. It's counted the same way as in a report grouped by the field: only objects you can read, excluding archived ones. A field you can't read (or can read only in a narrower scope than the objects themselves) returns 403 FIELD_NOT_READABLE; a field of another type returns 422 VALIDATION_FAILED; type not found — 404 NOT_FOUND; a query that's too expensive — 422 QUERY_TOO_EXPENSIVE.

Recurring tasks

Recurrence turns an object into a series: following the rule, Flow creates the next objects itself — copies of the series' last object with a new due date. A series is tied to the object it started from and to all created copies: GET /objects/{id}/recurrence on any of them returns the same series.

Rule

PUT /objects/{id}/recurrence and POST /objects/{id}/recurrence/preview accept a rule:

Field

Type

Description

mode

string

schedule (default) — by the calendar, whether or not the previous task is closed; after_done — the next task appears when the last one is closed

freq

string

Required: daily, weekdays (Mon–Fri, schedule only), weekly, monthly, yearly

interval

integer

Every N days, weeks, months or years, 1–365, default 1. For weekdays, only 1

weekdays

array

weekly only: days mo, tu, we, th, fr, sa, su. Without them, the weekday of the due date

month_day

integer

monthly and yearly: day of the month 1–31, or -1 for the last day

month_week

object

monthly only: {"week": 1…4 or -1, "day": "tu"} — for example, the second Tuesday. Can't be combined with month_day

month

integer

yearly only: month 1–12

end

object

{"type": "never"} (default), {"type": "until", "until": "2026-12-31"} (date inclusive) or {"type": "count", "count": 10} — 2–1000 occurrences, including the first task

timezone

string

IANA time zone, for example Europe/Moscow. Defaults to the zone of the workspace's working calendar; if the calendar isn't set up, the zone is required

lead_days

integer

schedule only: how many days before the date to create the task, 0–30, default 1. The task is created at 00:00 in the series' time zone

due_field

string

The due date field (date or datetime); defaults to due_date, otherwise the type's first date field

Missing parts of the schedule are taken from the anchor date — the object's due date, or today's date if it has none: weekly without weekdays uses its weekday, monthly its day of the month, yearly its month and day. Days 29–31 in a shorter month move to the last day of the month. In after_done mode, the next task's due date is the previous task's close date plus interval days, weeks, months or years.

Make an object recur

curl -X PUT https://flow.sensever.com/v1/objects/$OBJECT_ID/recurrence \
  -H "Authorization: Bearer $SENSEVER_API_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Idempotency-Key: repeat-report-weekly-1" \
  -H "Content-Type: application/json" \
  -d '{
    "freq": "weekly",
    "weekdays": ["mo", "th"],
    "end": {"type": "until", "until": "2026-12-31"},
    "timezone": "Europe/Moscow",
    "lead_days": 1
  }'

Response 200 is {"series": …}:

{
  "series": {
    "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f20",
    "object_type_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b91",
    "rule": {"mode": "schedule", "freq": "weekly", "interval": 1, "weekdays": ["mo", "th"], "end": {"type": "until", "until": "2026-12-31"}, "timezone": "Europe/Moscow", "lead_days": 1},
    "status": "active",
    "end_reason": null,
    "last_error": null,
    "anchor_date": "2026-09-28",
    "due_field": "due_date",
    "start_field": "start_date",
    "sequence": 1,
    "created_count": 1,
    "next_date": "2026-10-01",
    "next_create_at": "2026-09-29T21:00:00.000000Z",
    "upcoming": ["2026-10-01", "2026-10-05", "2026-10-08", "2026-10-12", "2026-10-15"],
    "last_object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
    "principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
    "revision": 1,
    "created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
    "created_at": "2026-09-26T10:00:00.000000Z",
    "updated_at": "2026-09-26T10:00:00.000000Z"
  }
}

Field

Description

rule

The rule after normalization: missing parts are filled in

status

active; stopped — stopped by a person; ended — finished

end_reason

stopped, count, until, source_missing (all tasks of the series are archived), failed (a copy couldn't be created) or null

last_error

The error for failed: {code, message}, for example PERMISSION_DENIED if the rule's author no longer has permission to create objects

anchor_date

Anchor date

due_field, start_field

The due date and start date fields the series shifts

sequence, created_count

Number of the last occurrence (including dates skipped after downtime) and how many tasks the series has

next_date, next_create_at

Date of the next task and when it will be created (for after_done, null until the task is closed)

upcoming

Up to 5 upcoming dates of an active series

last_object_id

The series' last task — the template for the next copy

principal_id

On whose behalf copies are created: whoever last set the rule

revision

Rule number, increments with each PUT

Rules:

  • A new series starts from the object in the path. A PUT for an object that already has a series replaces the rule (revision + 1), and the series continues from the last task. A stopped or ended series starts again.

  • What's copied: title, assignee, fields by data type (a checklist without checkmarks), many-to-one relations (project, milestone, parent). The copy's due date is the occurrence date, and the start date shifts by the same number of days. Other dates, blockers, discussion, files and history aren't copied.

  • Who creates them. Copies are created on behalf of principal_id with their permissions. If a copy can't be created (no permission, a required field, an archived type), the series ends with status ended and end_reason: failed.

  • Downtime. If the server was down, only the nearest missed task is created after it starts, and the missed dates count toward count.

  • In webhooks, a created copy is an ordinary object.created event with actor.type = "automation" (see Flow API: webhooks).

Errors: object not found or you can't read it — 404 OBJECT_NOT_FOUND; object archived — 409 OBJECT_ARCHIVED; no object.update — 403 PERMISSION_DENIED. Rule errors all come at once — 422 VALIDATION_FAILED with details.fields[{field, code, messages}]: required, invalid_value, out_of_range, not_allowed, invalid_date, invalid_timezone, unknown_property, never_fires (the rule produces no dates), unknown_field, field_not_date, type_not_published.

Read and stop

  • GET /objects/{id}/recurrence returns the object's series in any status, or {"series": null}.

  • DELETE /objects/{id}/recurrence stops it: no new tasks are created, the scheduled one is canceled, and created ones stay. The response is the stopped series; a repeat returns the same series, and an object without a series returns {"series": null}. You can also stop it on an archived object.

Preview

POST /objects/{id}/recurrence/preview with the same body as PUT saves nothing and returns the anchor date and up to 5 upcoming dates:

{"anchor_date": "2026-09-28", "dates": ["2026-10-01", "2026-10-05", "2026-10-08", "2026-10-12", "2026-10-15"]}

For after_done, dates has one date — the next task's due date if you close this one today. Errors are the same as for PUT, but permission to read the object is enough.

Which objects recur

POST /recurrence/lookup with {"object_ids": [...]} (up to 500 ids) returns the active series of these objects, for the recurrence icon on boards and tables:

{"items": [{"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72", "series_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f20", "mode": "schedule", "next_date": "2026-10-01"}]}

Objects without an active series or without read permission are absent from the response. More than 500 ids returns 422 VALIDATION_FAILED.

What's next

Коментарі

Автори