Flow API: workspace, access and notifications

SENSEVER

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

約 20 分で読めます

Flow API: workspace, access and notifications

This article covers the methods that manage the workspace itself: its settings, members, invitations, roles and permissions, teams, service keys, and personal notification settings. For how roles and invitations work from the user's point of view, see Flow: members, roles, teams and billing.

All methods work in the workspace from X-Workspace-Id (or the workspace of a flw_… key) and check the caller's permissions. Permissions in the tables are written as resource.action, for example workspace.manage. General rules are in Flow API: basics.

Methods for a user session only

Some methods don't work within a single workspace but on behalf of a person across all of their workspaces. They're called by the Flow interface on sensever.com (a browser session or an embed token). API keys get 401 UNAUTHENTICATED: a key is issued for selected workspaces, while these methods by design cover all of a person's workspaces, or one that doesn't exist yet.

Method

Request

What it does

Me and my workspaces

GET /me

The user (id, email, display_name) and the workspaces where they're an active member: id, name, status, role_keys, principal_id, is_system

Create a workspace

POST /workspaces

A new workspace from a template; the creator becomes the owner

Objects from all workspaces

POST /me/objects/query

"All workspaces" mode: one page of objects from all of the person's workspaces

Approvals from all workspaces

GET /me/approvals

Approvals assigned to the person across all workspaces; see Flow API: processes, approvals and external events

Summary across all workspaces

POST /me/reports/summary

Counts by status category, overdue, assignee, workspace and week; see Flow API: reports, SLA and business calendar

Calendar and filters for all workspaces

POST /me/objects/calendar, GET /me/objects/filters

"All objects" as a calendar, options for the "Type" and "Assignee" filters

"By section"

GET /me/tasks, GET /me/tasks/counts, PATCH /me/tasks/settings, PUT /me/tasks/sections/{section_id}/order

The person's tasks from all workspaces in personal sections

Calendar subscription

GET, POST /me/calendar-feeds, DELETE /me/calendar-feeds/{id}

Secret iCalendar links to due dates

Email

GET, PATCH /me/mail-settings

Daily digest and notification emails, one set of settings for all workspaces

My invitations

GET /invitations

Workspace invitations addressed to the person

Respond to an invitation

POST /invitations/{workspace}/{invitation}/respond

{"decision": "accepted"} or "declined"

The calendar, "By section", calendar subscriptions and email are described in Flow API: personal lists, calendar and email. The subscription document itself, GET /calendar-feeds/{token}, is public: the secret is in the URL.

For an integration, this means you know a key's list of workspaces when you issue it, and you read objects one workspace at a time — POST /objects/query with the right X-Workspace-Id. A key can't create a workspace or accept an invitation on a person's behalf.

is_system: true marks the person's primary workspace, Main: it can't be renamed or deleted (422 VALIDATION_FAILED, details.reason = system_workspace).

POST /workspaces

Field

Type

Description

name

string, required

Name, up to 200 characters

template

string

Template: blank (default, empty), tasks, crm, product; starter is the Main workspace template

template_file

object or null

A template file instead of a system template, see "Template files" below. Only without template or with blank

search_language

string or null

Full-text search language from GET /search/settings; defaults to simple

locale

string or null

Language of the names the template creates: ru, az, bn, de, en, es, fr, hi, id, it, ja, kk, ko, nl, pl, pt, th, tr, uk, uz, vi, zh

timezone

string or null

The creator's IANA time zone (for example, Europe/Moscow) for the template's reminder rules: reminders arrive at 09:00 in this zone. Offsets (+03:00) and abbreviations (MSK) aren't accepted. Defaults to the main zone of the template language (ru → Europe/Moscow, en → UTC)

{ "name": "Sales", "template": "crm", "locale": "en", "search_language": "english" }

locale translates the names of types, fields and options, statuses and transitions, views, action buttons, rules, and the texts of their notifications. Keys (deal, won, amount, etc.), expressions and settings are the same in every language, so integrations work the same way with a workspace in any language. The Flow interface passes the creator's interface language. Without locale (or with null), the language comes from search_language (english → en, german → de, and so on), otherwise it's ru. Any other value, including en-US or EN, returns 422 VALIDATION_FAILED. Names are saved as workspace data: you can change them later, and changing the interface language doesn't rename them.

Response 201: workspace, the creator's principal_id (role owner) and template_result — which template steps were applied (applied) and which were skipped (skipped, with a reason). Ready-made template automations that need no setup are created enabled (the list is in Flow: automations); a rule with a webhook to an external system stays a disabled draft until a URL is set. One person can be a member of at most 50 workspaces. With an Idempotency-Key header, a repeated request returns the saved response and doesn't create a second workspace.

POST /me/objects/query

Reads objects from all of the person's active workspaces in one page. Body:

Field

Description

sort

{"by": "updated_at" or "created_at", "dir": "asc" or "desc"}; defaults to updated_at

page

{"size": 1–100, "cursor": …}

filter.workspace_ids

Only these workspaces (up to 100)

filter.state_categories

Status categories: open, in_progress, done, cancelled

filter.owner_user_id

me, none (objects without an assignee) or a Flow user id (user.id from GET /me, a member's user_id, or one from GET /me/objects/filters)

filter.type_keys

Only types with these keys, 1–50. The same key in different workspaces counts as one type; the options are types from GET /me/objects/filters

filter.title_contains

Case-insensitive title substring, up to 200 characters

filter.search

Full-text search, up to 200 characters

filter.due

Due date range on the type's due_date or due_at field

Each response item is a compact summary: id, workspace (id, name, is_system), type, title, state, owner (principal_id, user_id, name, picture_url; user_id and name are null if you don't have workspace.read in that workspace), due, version, created_at, updated_at. A page reads at most 50 workspaces and has a time budget; workspaces that weren't read are listed in meta.skipped_workspaces, and meta.partial is true.

Workspace

Method

Request

Permission

Read

GET /workspace

workspace.read

Rename, change quotas

PATCH /workspace

workspace.manage

Delete

DELETE /workspace

workspace.delete (owner)

The response contains id, name, plan, status (active, suspended, deleted), quotas, is_system, created_at, updated_at.

PATCH /workspace accepts name (up to 200 characters) and quotas — an object merged by key; null for a key restores the default value. Supported quotas: api_requests_per_minute, api_principal_requests_per_minute, queue.<queue|*>.weight, queue.<queue|*>.max_concurrency, queue.<queue|*>.rate_per_minute, indexed_multi_value_items, indexed_fields_per_type, indexed_fields_total, projection_rows.

DELETE /workspace requires confirmation with the exact name:

{ "name": "Sales department" }

The response is {"deleted": true}. The workspace is marked as deleted and access is closed for all members and keys; further requests to it are rejected at authorization. The data isn't physically deleted.

Template files

A custom template is a file: you can download a type or a whole workspace, then create a type from the file in any workspace, or a new workspace. Templates aren't stored on the server, and there's no shared template list. In the interface, these are the "Download template" and "Upload template" buttons.

Method

Request

Permission

Download a type or workspace as a file

GET /templates/file

schema.manage

Create a type from a file

POST /templates/file/apply

schema.manage plus step permissions: view.manage, automation.manage, process.manage

New workspace from a file

POST /workspaces with template_file

user session only

Presets for the "New type" form

GET /type-presets

schema.read

Create a type from a preset

POST /type-presets/{key}/apply

same as creating from a file

Download

GET /templates/file?kind=type&object_type=task returns one published type; GET /templates/file?kind=workspace returns all published types of the workspace. The file includes fields, the status process, restrictions, shared views, action buttons, automations, reminder rules, processes, relations between the file's types, and shared dashboards. The file contains no data: no objects, files, comments, members or personal views. References to specific people are replaced with roles or the object's assignee, and automations with call_webhook are left out.

{
  "file": {"format": "sensever-flow-template", "version": 1, "kind": "type", "name": "Tasks", "definition": {}},
  "skipped": [{"kind": "automation", "name": "Send to ERP", "object_type": "task", "reason": "webhook"}],
  "skipped_total": 1
}

skipped lists what didn't make it into the file (first 50), with a reason: webhook, instance_reference (a reference to a person, an object or a custom role), outside_template, unpublished, disabled. Save file as is — you don't need to parse definition. Errors: no object_type with kind=type — 422 with required; type not found — 404 NOT_FOUND; type not published — 422 with unpublished; no published types in the workspace — 422 with empty_workspace.

Create a type from a file

POST /templates/file/apply:

Field

Description

file

The file object from the download response, required. Only kind: "type"

type_name, plural_name

Singular and plural name of the main type, up to 200 characters; defaults to the names in the file

key

Key of the main type; must be free (422 with key_exists)

timezone

IANA time zone for reminder rules; defaults to the zone of the workspace's working calendar

Everything is created in one transaction: an error in any step rolls back the whole file. Taken keys of other types, relations and processes get a suffix _2, _3… Response 201: object_type (id, key, name, plural_name), object_types — all created types, and applied — the number of applied steps by kind. File errors return 422 VALIDATION_FAILED: invalid_file (not a Sensever Flow template file), wrong_kind (a workspace file — upload it when creating a workspace), invalid_definition; a definition larger than 256 KB returns 422 LIMIT_EXCEEDED.

POST /workspaces accepts a workspace file (and a type file too) in the template_file field: the new workspace gets the types and settings from the file with the file's names, untranslated; the request's timezone sets the zone for reminder rules.

Members

Method

Request

Permission

List members

GET /workspace/members

workspace.read

Change roles or status

PATCH /workspace/members/{principal_id}

workspace.manage

Disable a member

DELETE /workspace/members/{principal_id}

workspace.manage

A member has principal_id, user_id, email, display_name, picture_url, role_keys (system roles), role_ids (all roles), team_ids, status (active, disabled, pending), created_at.

The name and photo come from the Sensever profile and are the same in every workspace: a rename or a new photo in the profile reaches Flow automatically. picture_url is an https URL of the photo, or null if there's no photo — in that case, draw initials.

PATCH accepts one of the two role fields, plus status:

Field

Description

role_keys

Replaces system roles (up to 5); the member's custom roles stay

role_ids

Replaces the whole set of roles, system and custom (up to 10 ids); an unknown id returns 422 with unknown_role

status

active or disabled

Rules:

  • changing the owner role (or a role with the workspace.delete permission) and disabling an owner require workspace.delete;

  • the last active owner can't lose the role or be disabled — 422 VALIDATION_FAILED;

  • DELETE doesn't remove a member but disables them: the record stays for history and auditing. Repeating it is safe;

  • when a member is disabled, all their flw_… keys are revoked and their webhook subscriptions are turned off.

You can't add a member directly: a person joins a workspace only by accepting an invitation.

Invitations

Method

Request

Permission

Find a person in Sensever

GET /workspace/people?q=…

workspace.manage

Open invitations

GET /workspace/invitations

workspace.manage

Invite

POST /workspace/invitations

workspace.manage; the owner role also needs workspace.delete

Cancel an invitation

DELETE /workspace/invitations/{invitation}

workspace.manage

GET /workspace/people searches the Sensever people directory, not just Flow users: @name matches the beginning of a username; a name, email or phone number matches only exactly (a phone number only if the person has verified it and not hidden it). A query shorter than 2 characters finds nothing. The response contains accounts_id, name, username, picture_url, match (what matched) and state: member — already a member, invited — already invited, null — neither. Email and phone are not returned.

An invitation:

{ "accounts_id": "12345", "role_keys": ["member"] }

or by email:

{ "email": "anna@example.com", "role_keys": ["viewer"] }
  • role_keys are system roles, up to 5, default ["member"]. A custom role is assigned after acceptance via PATCH /workspace/members/{principal_id} with role_ids.

  • An email that belongs to a Sensever account invites that person. For any other email, Sensever Accounts sends a message, and the invitation waits until a person with that verified email accepts it. The letter field shows what happened to the email: sent, registered, limited, failed.

  • Nothing is created in the workspace until the invitation is accepted.

  • Inviting the same person or email again returns the open invitation unchanged with code 200; a new one returns 201.

  • 422 VALIDATION_FAILED reasons: target_required, invalid_email, user_not_found, already_member, unknown_role.

You can cancel only an invitation that hasn't been answered; an answered one returns 422.

Roles and permissions

Method

Request

Permission

Roles with permissions

GET /workspace/roles

workspace.read

One role

GET /workspace/roles/{id}

workspace.read

Create a custom role

POST /workspace/roles

workspace.manage

Rename a custom role

PATCH /workspace/roles/{id}

workspace.manage

Delete a custom role

DELETE /workspace/roles/{id}

workspace.manage

Replace role permissions

PUT /workspace/roles/{id}/permissions

workspace.manage

A role has id, key (the system role key, or null for a custom role), name, system, member_count, permissions[], created_at. The list is ordered as follows: the system roles owner, admin, member, viewer, integration, then custom roles by name.

Permission row

Field

Description

resource

object, field, transition, object_action, automation, process, schema, view, integration, workspace

action

read, create, update, archive, execute, manage, delete — depending on the resource

scope

all — all objects, team — your team's objects, own — your own, none — nothing

object_type_id

The type the row applies to; null means all types

field_id

Required for field

transition_key

Required for transition; * means all transitions of the type

object_action_key

Only for object_action; null means all actions of the type

System role permissions in a new workspace (templates may add to them):

Permission

owner

admin

member

viewer

integration

object.read

all

all

all

all

all

object.create

all

all

all

—

all

object.update

all

all

team

—

all

object.archive

all

all

own

—

all

transition.execute

all

all

team

—

all

object_action.execute

all

all

team

—

all

automation.read

all

all

all

all

all

automation.execute, automation.manage

all

all

—

—

—

process.read

all

all

all

all

all

process.execute

all

all

all

—

all

process.manage

all

all

—

—

—

schema.read

all

all

all

all

all

schema.manage

all

all

—

—

—

view.read

all

all

all

all

all

view.manage

all

all

own

—

—

integration.read, integration.manage

all

all

—

—

all

workspace.read

all

all

all

all

all

workspace.manage

all

all

—

—

—

workspace.delete

all

—

—

—

—

What you can change

  • Custom roles — everything: the name (1–80 characters, unique case-insensitively), permissions, deletion. POST /workspace/roles accepts name and copy_from — the id of a role whose permissions to copy (a system role works too).

  • System roles can't be renamed or deleted (422, system_role_readonly). The permissions of admin, member and viewer can be changed; those of owner and integration can't.

  • PUT /workspace/roles/{id}/permissions atomically replaces the whole set of rows: {"permissions": [ … ]}, up to 2000 rows. A matching row keeps its id. Errors point to permissions[i] or permissions[i].<field>: unknown_object_type, unknown_field, field_not_in_object_type, duplicate, too_many.

  • Only someone who has the workspace.delete permission can grant, copy or remove it.

  • A role that is someone's only role can't be deleted: 422 with in_use, details.principal_count and details.principal_ids (up to 100).

Role POST and PATCH and PUT …/permissions support Prefer: return=minimal: the response is then a compact DefinitionResult, and the full role is available at GET /workspace/roles/{id}.

Example: a "Managers" role — a copy of member that is allowed to change all objects of the deal type:

curl -s https://flow.sensever.com/v1/workspace/roles \
  -H "Authorization: Bearer $FLOW_KEY" -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Managers", "copy_from": "<member role id>" }'

Then read its permissions (GET /workspace/roles/{id}), add the row {"resource": "object", "action": "update", "scope": "all", "object_type_id": "<deal type id>"} and send the whole set to PUT /workspace/roles/{id}/permissions.

Permissions only allow

There are no denying rows: the effective permission is the broadest of all matching rows across all of the member's roles. A row with object_type_id: null applies to all types, and a row for a single type can't narrow it. So a role that works with only one type is built like this: it has no object, transition or object_action rows without a type, only rows for the type it needs.

Example: a purchasing department role sees and changes only objects of the purchase type. Create the role as a copy of member (so it keeps the schema.read, view.read, workspace.read rows and other basic workspace permissions), remove the object.*, transition.execute and object_action.execute rows with object_type_id: null from the set, and add rows for the type:

{
  "permissions": [
    {"resource": "object", "action": "read", "scope": "all", "object_type_id": "<purchase type id>"},
    {"resource": "object", "action": "create", "scope": "all", "object_type_id": "<purchase type id>"},
    {"resource": "object", "action": "update", "scope": "all", "object_type_id": "<purchase type id>"},
    {"resource": "transition", "action": "execute", "scope": "all", "object_type_id": "<purchase type id>", "transition_key": "*"},
    {"resource": "object", "action": "archive", "scope": "own", "object_type_id": "<purchase type id>"}
  ]
}

Only the object rows are shown here; PUT replaces the whole set, so send them together with the role's other rows. Then assign the role to staff via PATCH /workspace/members/{principal_id} with role_ids, replacing the system role: if a person keeps member or viewer, they'll still see all types. When it's better to set up a separate workspace for the department is explained in Flow: members, roles, teams and billing.

Teams

A team is a group of members. It defines the team scope in permissions: "your team's objects".

Method

Request

Permission

List teams

GET /workspace/teams

workspace.read

Create

POST /workspace/teams {"name": "…"}

workspace.manage

Rename

PATCH /workspace/teams/{id} {"name": "…"}

workspace.manage

Delete

DELETE /workspace/teams/{id}

workspace.manage

Replace members

PUT /workspace/teams/{id}/members {"member_ids": [ … ]}

workspace.manage

A team has id, name, member_ids (principal ids of members), created_at. The name is 1–80 characters, unique case-insensitively. A team can include up to 1000 of the workspace's human members (active or disabled); an id from elsewhere returns 422 with unknown_member. Roles aren't assigned to teams: they're granted to members.

Workspace keys

Besides platform keys from the Sensever profile, a workspace has service keys flw_<prefix>_<secret>. They're useful when an integration should act as a service member or with narrow permissions.

Method

Request

Permission

List keys (without secrets)

GET /api-credentials

integration.read

Issue a key

POST /api-credentials

integration.manage; for another member, also workspace.manage

Revoke a key

DELETE /api-credentials/{id}

integration.manage

Issue body:

Field

Description

principal_id

On whose behalf the key acts; defaults to the caller

scopes

Key scopes, up to 50; empty means all of the member's permissions

expires_at

An expiry in the future; null means no expiry

Response 201 contains secret — the full key for Authorization: Bearer. It's shown once; a repeat with the same Idempotency-Key returns secret: null. The list shows key_prefix, scopes, expires_at, last_used_at (updated at most once a minute) and revoked_at. A revoked key gets 401 immediately.

Key scopes

The format is <resource>:<action> or <resource>:*:

Resource

Actions

object

read, create, update, archive, restore

field

read, update

transition

execute

object_action

execute

automation

read, execute, manage

process

read, execute, manage

schema

read, manage

view

read, manage

integration

read, manage, ingest_events

workspace

read, manage, delete, suppress_automations

  • Any action on a resource includes its read; object:<action> covers field:<action>; object:archive covers restore.

  • A key is never broader than its member: both scopes and roles apply. A scope denial returns 403 with details.reason = key_scope.

  • An unknown scope returns 422 with unknown_scope. objects:read and object.read are accepted and saved as object:read.

  • A key with scopes can only issue keys no broader than itself, and can manage webhooks only if it has object:read.

For example, a key for ingesting events from an external system: ["integration:ingest_events"]; a read-only key for tasks: ["object:read"].

My notifications

A person's personal notification settings in the current workspace. Any valid key can read and change them — it changes the settings of its owner.

Method

Request

Read

GET /workspace/notification-settings

Change

PATCH /workspace/notification-settings

Field

Description

muted

true — nothing arrives from this workspace

categories.automations

Automation notifications

categories.reminders

Due date reminders

categories.approvals

Everything from processes: approvals, escalations, step notifications

categories.mentions

Mentions: someone named you with @ in a text field of an object you can read (for example, in the description)

channels.chat

A message in the conversation with "Sensever Flow"; when off, no message arrives in chat

channels.push

Push for that message; when off, the message arrives silently

channels.email

Notification emails from this workspace; off by default

email_categories

Which categories also arrive by email when channels.email is on: automations, reminders, approvals, mentions. Defaults to reminders and approvals

quiet_hours

{"from": "22:00", "to": "08:00", "timezone": "Europe/Moscow"} or null; during quiet hours, messages arrive without push

muted_automations

Ids of automations whose notifications are off (up to 500)

muted_reminder_rules

Ids of reminder rules that are off (up to 500)

sources

Read-only: what can notify the person here (kind: automation or reminder_rule, id, name, object_type, muted)

If both chat and email are off for a category, notifications in that category aren't delivered at all. An email isn't sent right away: one email collects everything that arrived during the wait, at most once every 15 minutes and not before quiet hours end. Notification emails in general, the daily digest, and the email time zone and language are personal settings for all workspaces: GET and PATCH /me/mail-settings, user session only (see Flow API: personal lists, calendar and email).

PATCH is a partial update: categories, channels and email_categories are merged by key, while quiet_hours and the lists of muted sources are replaced entirely. Error codes in details.fields[].code: required, unknown_property, invalid_value, invalid_time, invalid_timezone, unknown_automation, unknown_reminder_rule.

curl -s -X PATCH https://flow.sensever.com/v1/workspace/notification-settings \
  -H "Authorization: Bearer $FLOW_KEY" -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -d '{ "categories": { "reminders": false }, "channels": { "email": true }, "email_categories": { "mentions": true }, "quiet_hours": { "from": "21:00", "to": "09:00", "timezone": "Europe/Moscow" } }'

Who gets notifications and when is described in Flow: notifications and reminders.

Search language

Method

Request

Permission

Read

GET /search/settings

any member

Change

PUT /search/settings {"language": "russian"}

workspace.manage

The response contains language (the current language of the full-text index) and languages (the supported ones). The default is simple: no word-form handling, words match by prefix. After a language change, the response contains reindex: true: objects are reindexed in the background, and until that finishes, search finds only objects already reindexed. How to search is covered in Flow API: query language and search.

コメント

著者