Flow API: personal lists, calendar and email
This article describes a person's personal methods, which work across all of their workspaces at once: "All objects" as a calendar and the filter options, "By section" (the person's tasks in personal sections), a calendar subscription via an iCalendar link, and email settings. These are the methods behind the "All workspaces" mode of the Flow interface on sensever.com.
General rules — the address, headers and error format — are in Flow API: basics. For how this looks in the interface, see Flow: all workspaces and Flow: email and calendar subscription.
Who can call these methods
All methods in this article, except the calendar document itself, work only on behalf of a person: with a browser session (the flow_session cookie) or with the embed token that sensever.com obtains for its Flow interface.
API keys get
401 UNAUTHENTICATED— both a Sensever platform key and aflw_…workspace key. A key is issued for specific workspaces, while these methods cover all of a person's workspaces or their personal settings. An integration reads objects one workspace at a time:POST /objects/querywith the relevantX-Workspace-Id.X-Workspace-Idis not needed and is ignored.With a browser session, modifying requests require the
X-CSRF-Tokenheader set to the value of theflow_csrfcookie.These methods accept
Idempotency-Keybut don't use it: they have no workspace, and repeating a request is either safe in itself or described for the method.Responses are not cached (
Cache-Control: no-store, private).
GET /calendar-feeds/{token} is public: the subscription secret is in the address itself, so neither a session nor a key is needed.
Methods
Method | Request | What it does |
|---|---|---|
Objects from all workspaces |
| One page of objects; described in Flow API: workspace, access and notifications |
Calendar across all workspaces |
| Objects with a due date in a range of days |
Filter options |
| Types and people for the "Type" and "Assignee" filters |
Tasks by section |
| The person's open tasks in all workspaces, arranged in personal sections |
Task counters |
| Overdue and due today |
Section settings |
| Sections, the "Today" auto rule, grouping, quick add |
Order within a section |
| Put tasks into a section in the desired order |
Subscription links |
| Active calendar links |
Issue a link |
| A new secret iCalendar link |
Revoke a link |
| Revoke the link |
Calendar document |
| An iCalendar file for Google Calendar, Apple Calendar, Outlook; public |
Email settings |
| Daily digest, notification emails, email time zone and language |
Paths are relative to https://flow.sensever.com/v1.
How all workspaces are read
In each workspace where the person is an active member, the request runs on behalf of their member there: the own and team scopes of the object.read permission, field permissions and cost thresholds apply, as with POST /objects/query. Suspended workspaces and workspaces where the membership is disabled are not read.
One request reads no more than 50 workspaces, and there is a time budget. A workspace that couldn't be read goes into meta.skipped_workspaces[] (id, name, reason, sometimes error_code), and meta.partial becomes true; the other workspaces are still returned. reason values: not_available (the person doesn't have the requested workspace), workspace_suspended, workspace_limit, time_budget, error. Ignore unknown values. meta.workspaces_scanned is the number of workspaces read.
Each object comes with workspace (id, name, is_system): to open or change it, pass X-Workspace-Id = workspace.id.
All objects: calendar and filters
List filters
POST /me/objects/query is described in Flow API: workspace, access and notifications. The "Assignee" filter is filter.owner_user_id: me, none (objects without an assignee) or a Flow user id; the "Type" filter is filter.type_keys, 1–50 type keys. The same key in different workspaces counts as one type. The calendar accepts the same filters.
POST /me/objects/calendar
Objects from all workspaces whose due date falls within a range of days, plus objects whose "start — due date" bar overlaps the range.
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | First day, |
| string | yes | Last day, inclusive; no more than 62 days from |
| string | no | IANA time zone whose days are used to place dates and times; defaults to |
| array | no | Only these workspaces, 1–100 |
| array | no |
|
| string | no |
|
| array | no | 1–50 type keys |
| string | no | Full-text search, 1–200 characters |
A type's due date field is the first of due_date (date) and due_at (date and time), and the start field is the first of start_date and start_at. Types without a due date field don't appear in the calendar; a type whose due date you can't see yields no objects; an invisible start field is ignored.
curl -X POST https://flow.sensever.com/v1/me/objects/calendar \
-H "Cookie: flow_session=…; flow_csrf=…" \
-H "X-CSRF-Token: $FLOW_CSRF" \
-H "Content-Type: application/json" \
-d '{"from": "2026-09-28", "to": "2026-11-01", "tz": "Europe/Moscow", "filter": {"owner_user_id": "me", "type_keys": ["task"]}}'{
"from": "2026-09-28",
"to": "2026-11-01",
"time_zone": "Europe/Moscow",
"items": [
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"workspace": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "name": "Main", "is_system": true},
"type": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b91", "key": "task", "name": "Task"},
"title": "Prepare the contract",
"state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c01", "key": "in_progress", "category": "in_progress"},
"owner": {"principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74", "user_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b75", "name": "Anna Smith", "picture_url": null},
"due": "2026-10-01", "due_kind": "date", "due_on": "2026-10-01",
"start": "2026-09-29", "start_kind": "date", "start_on": "2026-09-29",
"version": 12
}
],
"meta": {"workspaces_scanned": 3, "skipped_workspaces": [], "partial": false, "truncated": false}
}dueandstartare the field values as is;due_onandstart_onare the days of those values in thetztime zone.start,start_kindandstart_onarenullif there is no start field or it isn't visible.owneris the assignee:user_idandnameare included only if you haveworkspace.readin that workspace;picture_urlis the photo from the Sensever profile ornull.Objects are sorted by due day, start day and title. No more than 1000 objects:
meta.truncated: truemeans there are more matches, so narrow the filters.Errors are
422 VALIDATION_FAILED:fromortoisn't a date,tois earlier thanfromor the range is longer than 62 days (invalid_range), an invalidtz, an unknown filter key (unknown_key).
GET /me/objects/filters
Options for the "Type" and "Assignee" filters:
{
"types": [{"key": "task", "name": "Task", "workspace_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70"], "has_due": true}],
"people": [{"user_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b75", "name": "Anna Smith", "picture_url": null, "is_me": true, "workspace_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70"]}],
"meta": {"workspaces_scanned": 3, "skipped_workspaces": [], "partial": false}
}types— published types you can read, merged by key;namecomes from the workspace that is first by name;has_duemeans the type has a due date field in at least one workspace (so it can appear in the calendar).people— active people in workspaces where you haveworkspace.read, merged by Flow user. You are always in the list yourself (is_me: true). Passuser_idinfilter.owner_user_id.
By section
"By section" shows the open tasks a person is responsible for (owner) from all their workspaces, arranged in personal sections. Sections and the order of tasks in them are the person's personal settings, shared across all workspaces.
A task here is an object of a published type whose process has a status of category done and which has a due date field (due_date or due_at) or a priority list field. Objects of other types don't appear in "By section".
GET /me/tasks
Parameter | Description |
|---|---|
| The person's IANA time zone: "today" and the day of a due date with time are calculated from it. Defaults to UTC |
|
|
curl "https://flow.sensever.com/v1/me/tasks?tz=Europe/Moscow" \
-H "Cookie: flow_session=…"Response:
Field | Description |
|---|---|
| Today's date in the time zone and the time zone itself |
| Tasks: |
|
|
| Personal settings: |
| Task types of each workspace that was read — for quick add: |
|
|
dueandpriorityare included only if you can read those fields.section_idis the section where the task is shown: the one the person put it in. A task without a placement (just assigned) is inrecent. Withsettings.auto_today, an open task due today or earlier is shown intoday(auto: true) unless it was put in a section of the person's own or moved to another section today.transitions— up to 20 transitions from the current status:key,name,to(key,name,category). To run a transition, usePOST /objects/{id}/transitions/{transition_key}withX-Workspace-Id=workspace.id.Placements of tasks that are no longer the person's tasks (reassigned, archived) and of workspaces the person has left are deleted on read.
No more than 500 tasks:
meta.truncated: truemeans the rest are not shown.
GET /me/tasks/counts?tz=… returns only the counters for the badge: {as_of, overdue, today, total, meta} for the same tasks.
Sections
Sections are an ordered list settings.sections[] of {id, kind, name}. Built-in sections: recent ("Recently assigned"), today ("Today"), week ("This week"), later ("Later"); their kind equals their id, and name: null means the default name in the interface language. Custom sections have kind: "custom" and a UUID id.
PATCH /me/tasks/settings changes only the keys you pass:
Field | Description |
|---|---|
| The complete new list of sections, in order: |
| Show open tasks due today or earlier in |
|
|
|
|
| The |
{
"expected_version": 3,
"sections": [
{"id": "recent"},
{"id": "today", "name": "Today's focus"},
{"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f60", "name": "Calls"},
{"id": "week"},
{"id": "later"}
]
}The response is the new settings with a new version. Errors are 422 VALIDATION_FAILED with paths like sections[2].name: builtin_required (a built-in section was removed), too_many, required (a custom section has no name), unknown_section, duplicate, invalid_value, unknown_key.
Order within a section
PUT /me/tasks/sections/{section_id}/order puts tasks into a section at positions 0…n-1 — this is drag and drop between sections and within a section. Pass the section's entire visible order.
{
"tz": "Europe/Moscow",
"items": [
{"workspace_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72"},
{"workspace_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b80", "object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b88"}
]
}The response is {"section_id": "today", "placed": 2, "placed_on": "2026-09-26"}. {section_id} is recent, today, week, later or the id of a custom section; an unknown section returns 404 NOT_FOUND. Up to 500 tasks; a workspace where the person isn't a member returns 422 on items[i].workspace_id (not_available); a task listed twice returns duplicate. The day of the move in the tz time zone is remembered for the "Today" rule. A placement doesn't grant access: the list shows only tasks the person can read. The request is idempotent by content.
Calendar subscription
A subscription is a secret link to an iCalendar document with due dates. The calendar app (Google Calendar, Apple Calendar, Outlook) re-reads the link on its own and shows due dates as events.
Issuing a link
POST /me/calendar-feeds:
without a body (or
{}) — all of the person's due dates: objects in all workspaces where they are the assignee;{"workspace_id": "…", "view_id": "…"}— a single calendar view of a workspace (both fields together).
curl -X POST https://flow.sensever.com/v1/me/calendar-feeds \
-H "Cookie: flow_session=…; flow_csrf=…" \
-H "X-CSRF-Token: $FLOW_CSRF" \
-H "Content-Type: application/json" \
-d '{}'Response 201:
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f70",
"scope": "all",
"workspace_id": null,
"view_id": null,
"title": "Sensever Flow",
"token_hint": "9f2c",
"created_at": "2026-09-26T10:00:00.000000Z",
"last_used_at": null,
"url": "https://flow.sensever.com/v1/calendar-feeds/…9f2c.ics",
"webcal_url": "webcal://flow.sensever.com/v1/calendar-feeds/…9f2c.ics"
}urlandwebcal_urlare shown only once and are not stored anywhere: Flow keeps only a fingerprint of the secret. Pasteurlinto Google Calendar ("From URL"); openwebcal_urlin Apple Calendar and Outlook.A new link revokes the previous active link with the same scope: for "all due dates", the previous all-due-dates link; for a view, the previous link to that view. Repeating the request issues one more link.
titleis the calendar name: "Sensever Flow" or "<workspace> · <view>".A view that isn't a calendar returns
422with the codenot_a_calendar; an unknown or inaccessible view or workspace returns404 NOT_FOUND; only one of the two fields returns422 VALIDATION_FAILED.
List and revocation
GET /me/calendar-feeds returns {"items": [...]} — active links, newest first, without the secret: only the last four characters, token_hint. last_used_at is when a calendar last fetched the link (updated no more than once an hour).
DELETE /me/calendar-feeds/{id} revokes the link: calendars subscribed to it get 404 from their next refresh. The response is the remaining active links in the same format as the list. An unknown, someone else's or already revoked link returns 404 NOT_FOUND.
Calendar document
GET /calendar-feeds/{token} (optionally with .ics at the end) returns an iCalendar document (RFC 5545), Content-Type: text/calendar. token is 64 hexadecimal characters.
Each object is one
VEVENTevent:UIDis the object id,SUMMARYis the title (with "✓" for completed objects),DESCRIPTIONis the workspace, type and status,URLis the object in Sensever,SEQUENCEis the object version, and cancelled objects getSTATUS:CANCELLED.A date due date becomes an all-day event (or a
start_date—due_datespan); a due date with time becomes a 30-minute event (or one fromstart_attodue_at).Objects are read at request time with the person's current permissions: revoked access disappears on the next refresh. The window is 30 days back and 365 days ahead, no more than 1000 events.
If the subscribed view was deleted or became inaccessible, the document comes back empty, and the link keeps working.
The link of a person whose account is disabled returns
404.
Limits: 60 documents per hour per link, 30 requests with an unknown token from one address in 10 minutes. Exceeding them returns 429 RATE_LIMITED with Retry-After. The response contains an ETag of the content: with If-None-Match, an unchanged document comes back as 304. Caching is Cache-Control: private, max-age=300, so there is no point in a calendar asking more often than once every 5 minutes.
GET /me/mail-settings returns the personal Flow email settings, shared across all workspaces:
{
"digest": {"enabled": false, "time": "08:00"},
"notifications": {"enabled": true},
"timezone": "Europe/Moscow",
"locale": "ru",
"timezone_set": true,
"locale_set": true
}Field | Description |
|---|---|
| Daily digest. Off by default |
| Digest time |
| Notification emails in general. Which notifications arrive by email is chosen in each workspace: |
| Email time zone and language. The interface sends the browser's time zone and language; until it does, the defaults apply, and |
The digest lists open objects where the person is the assignee, across all their workspaces and with their permissions: overdue ones, ones due today, and ones assigned to them by someone else in the last 24 hours. An empty digest is not sent. If the server didn't manage to send the digest within 4 hours after digest.time, that day's digest doesn't arrive.
Notification emails collect everything that arrived during the waiting period: one email no more than once every 15 minutes and not before the end of quiet hours. Emails are sent by Sensever Accounts to the account's verified address; each email has a one-click unsubscribe link. Anyone who unsubscribed via the link will see the setting turned off here.
PATCH /me/mail-settings is a partial update with at least one field; digest and notifications are merged by key.
curl -X PATCH https://flow.sensever.com/v1/me/mail-settings \
-H "Cookie: flow_session=…; flow_csrf=…" \
-H "X-CSRF-Token: $FLOW_CSRF" \
-H "Content-Type: application/json" \
-d '{"digest": {"enabled": true, "time": "09:30"}, "timezone": "Europe/Moscow"}'Turning on the digest or the emails also clears an unsubscribe made via the link in an email.
timezoneis an IANA time zone;localeis the site language (ru,en,deand others of the 22); a tag likede-ATis stored asde.The response is the settings after the change. Errors are
422 VALIDATION_FAILEDwithdetails.fields[].code:required(empty body),unknown_property,invalid_value,invalid_time,invalid_timezone,invalid_locale.
Errors
HTTP |
| When |
|---|---|---|
401 |
| A request with an API key or without a session |
403 |
| A modifying request with a session cookie has no |
404 |
| Unknown section, subscription link, view or calendar token |
409 |
| The |
422 |
| Invalid fields; codes are listed for each method |
429 |
| The calendar document is requested too often |
What's next
Flow: all workspaces — "All objects", "By section", "Approvals" and "Reports" in the interface.
Flow: email and calendar subscription — how to turn on the digest and subscribe a calendar.
Flow API: workspace, access and notifications —
POST /me/objects/queryand workspace notification settings.Flow API: basics — addresses, headers and errors.
Komen