Flow API: personal lists, calendar and email

SENSEVER

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

17 min bacaan

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 a flw_… 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/query with the relevant X-Workspace-Id.

  • X-Workspace-Id is not needed and is ignored.

  • With a browser session, modifying requests require the X-CSRF-Token header set to the value of the flow_csrf cookie.

  • These methods accept Idempotency-Key but 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

POST /me/objects/query

One page of objects; described in Flow API: workspace, access and notifications

Calendar across all workspaces

POST /me/objects/calendar

Objects with a due date in a range of days

Filter options

GET /me/objects/filters

Types and people for the "Type" and "Assignee" filters

Tasks by section

GET /me/tasks

The person's open tasks in all workspaces, arranged in personal sections

Task counters

GET /me/tasks/counts

Overdue and due today

Section settings

PATCH /me/tasks/settings

Sections, the "Today" auto rule, grouping, quick add

Order within a section

PUT /me/tasks/sections/{section_id}/order

Put tasks into a section in the desired order

Subscription links

GET /me/calendar-feeds

Active calendar links

Issue a link

POST /me/calendar-feeds

A new secret iCalendar link

Revoke a link

DELETE /me/calendar-feeds/{id}

Revoke the link

Calendar document

GET /calendar-feeds/{token}

An iCalendar file for Google Calendar, Apple Calendar, Outlook; public

Email settings

GET, PATCH /me/mail-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

from

string

yes

First day, YYYY-MM-DD, inclusive

to

string

yes

Last day, inclusive; no more than 62 days from from

tz

string

no

IANA time zone whose days are used to place dates and times; defaults to UTC

filter.workspace_ids

array

no

Only these workspaces, 1–100

filter.state_categories

array

no

open, in_progress, done, cancelled

filter.owner_user_id

string

no

me, none or a Flow user id

filter.type_keys

array

no

1–50 type keys

filter.search

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}
}
  • due and start are the field values as is; due_on and start_on are the days of those values in the tz time zone. start, start_kind and start_on are null if there is no start field or it isn't visible.

  • owner is the assignee: user_id and name are included only if you have workspace.read in that workspace; picture_url is the photo from the Sensever profile or null.

  • Objects are sorted by due day, start day and title. No more than 1000 objects: meta.truncated: true means there are more matches, so narrow the filters.

  • Errors are 422 VALIDATION_FAILED: from or to isn't a date, to is earlier than from or the range is longer than 62 days (invalid_range), an invalid tz, 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; name comes from the workspace that is first by name; has_due means 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 have workspace.read, merged by Flow user. You are always in the list yourself (is_me: true). Pass user_id in filter.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

tz

The person's IANA time zone: "today" and the day of a due date with time are calculated from it. Defaults to UTC

include_closed

true — also tasks closed (done or cancelled) in the last 7 days

curl "https://flow.sensever.com/v1/me/tasks?tz=Europe/Moscow" \
  -H "Cookie: flow_session=…"

Response:

Field

Description

today, time_zone

Today's date in the time zone and the time zone itself

items[]

Tasks: id, workspace, type (id, key, name), title, state (id, key, name, category), due, due_on, priority ({key, label} or null), transitions, section_id, auto, placement, version, created_at, updated_at, closed_at

counts

overdue, today, total — open tasks

settings

Personal settings: sections, auto_today, group_by, default_create, version

task_types[]

Task types of each workspace that was read — for quick add: workspace_id and type

meta

workspaces_scanned, skipped_workspaces, partial, truncated

  • due and priority are included only if you can read those fields.

  • section_id is the section where the task is shown: the one the person put it in. A task without a placement (just assigned) is in recent. With settings.auto_today, an open task due today or earlier is shown in today (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, use POST /objects/{id}/transitions/{transition_key} with X-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: true means 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

sections

The complete new list of sections, in order: [{id?, name?}]. Built-in sections must remain; they can be renamed and reordered. A custom section without an id is created (the id comes back in the response), or with your own UUID — then repeating the request won't create a second one. A custom section missing from the list is deleted, and its tasks return to recent. Up to 20 custom sections, names 1–100 characters

auto_today

Show open tasks due today or earlier in today

group_by

section, due or workspace

default_create

{workspace_id, type_key} for quick add, or null

expected_version

The version of the settings the change is based on; 0 means default settings not saved yet. A different version returns 409 OBJECT_VERSION_CONFLICT

{
  "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"
}
  • url and webcal_url are shown only once and are not stored anywhere: Flow keeps only a fingerprint of the secret. Paste url into Google Calendar ("From URL"); open webcal_url in 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.

  • title is the calendar name: "Sensever Flow" or "<workspace> · <view>".

  • A view that isn't a calendar returns 422 with the code not_a_calendar; an unknown or inaccessible view or workspace returns 404 NOT_FOUND; only one of the two fields returns 422 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 VEVENT event: UID is the object id, SUMMARY is the title (with "✓" for completed objects), DESCRIPTION is the workspace, type and status, URL is the object in Sensever, SEQUENCE is the object version, and cancelled objects get STATUS:CANCELLED.

  • A date due date becomes an all-day event (or a start_date — due_date span); a due date with time becomes a 30-minute event (or one from start_at to due_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.

Email

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

digest.enabled

Daily digest. Off by default

digest.time

Digest time HH:MM in the timezone time zone, 08:00 by default

notifications.enabled

Notification emails in general. Which notifications arrive by email is chosen in each workspace: channels.email and email_categories in PATCH /workspace/notification-settings

timezone, locale

Email time zone and language. The interface sends the browser's time zone and language; until it does, the defaults apply, and timezone_set and locale_set are false

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.

  • timezone is an IANA time zone; locale is the site language (ru, en, de and others of the 22); a tag like de-AT is stored as de.

  • The response is the settings after the change. Errors are 422 VALIDATION_FAILED with details.fields[].code: required (empty body), unknown_property, invalid_value, invalid_time, invalid_timezone, invalid_locale.

Errors

HTTP

error.code

When

401

UNAUTHENTICATED

A request with an API key or without a session

403

PERMISSION_DENIED

A modifying request with a session cookie has no X-CSRF-Token (details.reason = csrf)

404

NOT_FOUND

Unknown section, subscription link, view or calendar token

409

OBJECT_VERSION_CONFLICT

The expected_version of the "By section" settings is out of date

422

VALIDATION_FAILED

Invalid fields; codes are listed for each method

429

RATE_LIMITED

The calendar document is requested too often

What's next

Komen

Pengarang