Flow API: objects, transitions and relations
An object is a single Flow record: a task, a deal, a request. An object has a type, a title, field values, a status (its state in the process), an assignee and a version. This article covers everything you can do with one object: create, read, update, archive, history, status transitions, actions, relations, files and discussion.
The API address, authentication, the X-Workspace-Id and Idempotency-Key headers, the error format and limits are described in Flow API: basics. For how objects look in the interface, see Flow: the object card.
Methods
Method | Request | What it does |
|---|---|---|
Create an object |
| A new object of a type; |
Get an object |
| The object with the fields you are allowed to read |
Update an object |
| Fields, title, assignee; requires |
Archive |
| Move the object to the archive |
Restore |
| Bring the object back from the archive |
History |
| Changes, relations and transitions, newest first |
Available actions |
| Which transitions and actions are available to you right now |
Available actions in bulk |
| The same for 200 objects at a time |
Perform a transition |
| Change the status; |
Type actions |
| Action buttons configured for the type |
Create an action |
| A new button on top of a transition, field edits or a process |
Update an action |
| Label, configuration, placement, order, on/off switch |
Delete an action |
| Delete the action |
Run an action |
| Run the action's command |
Related objects |
| List of relations of one type |
Add a relation |
| Link to another object |
Remove a relation |
| Break the relation |
Relations of many objects |
| Related objects for 500 objects at a time |
Checklist items |
| Add, check, rename, reorder and delete items |
Files |
| The object's attachments and limits |
Start an upload |
| A file upload session in Sensever Assets |
Confirm an upload |
| Record the uploaded file as an attachment |
File link |
| A short-lived download link |
Delete a file |
| Delete the attachment |
Discussion |
| Access to the object's discussion in Sensever chat |
Who can be mentioned |
| People who can see the object, for an @mention |
Who can be mentioned in a new object |
| The same for the create form |
Admit mentioned people |
| Let mentioned people into the discussion before sending a comment |
Subtasks, recurrence and time tracking on an object are described in Flow API: subtasks, checklists and recurrence and Flow API: time tracking.
Paths are relative to https://flow.sensever.com/v1. Every request except those made with a workspace key needs the X-Workspace-Id header.
Object
GET /objects/{id} returns the object:
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"type": "deal",
"title": "Supply agreement",
"version": 28,
"state": {
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71",
"key": "won",
"category": "done",
"entered_at": "2026-09-16T10:00:00.000000Z"
},
"owner_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"schema_version": 3,
"lifecycle_version": 5,
"fields": {
"amount": {"amount": "150000.00", "currency": "EUR"},
"contract_signed": true
},
"created_at": "2026-09-01T08:00:00.000000Z",
"updated_at": "2026-09-16T10:00:00.000000Z",
"archived_at": null
}Field | Type | Description |
|---|---|---|
| UUID | Object ID |
| string | Object type key, for example |
| string or | Title |
| integer | Object version; increases with every change, including relation changes if the relation type bumps the version |
| object or | Current status: |
| UUID or | Assignee (the principal of a workspace member) |
| UUID | Who created the object |
| integer | The field schema version the object follows |
| integer or | Version of the object's status process |
| object | Field values by key. Fields you cannot read and relation fields are not included |
| object | Only when requested with |
| time | Creation and last change |
| time or | When the object was archived |
Field values
The value format depends on the field type:
Field type | JSON value |
|---|---|
| String; |
| Number |
| Integer |
|
|
|
|
|
|
|
|
| Option key |
| Array of option keys |
| Member UUID |
| Array of member UUIDs — for example, |
| Any JSON up to 64 KB |
| Array of items |
| Array of tag strings: up to 20 tags of 1–50 characters each. Leading and trailing spaces are trimmed, empty tags are skipped, case-insensitive duplicates are dropped |
| Not passed in |
Field types and their settings are described in Flow API: types, fields, statuses and publishing.
Response to a change
Commands that change an object (create, update, transition, archive, restore, action) return the same object, with these differences:
values larger than 1 KB are not included; their keys are listed in
omitted_fields— read full values withGET /objects/{id};includeis not supported;a transition response contains
transition_id— the ID of the recorded transition.
Such a response is always smaller than 64 KB, so a retry with the same Idempotency-Key returns it unchanged.
Creating an object
POST /v1/objects
X-Workspace-Id: 3f6c0d2e-1b7a-4c55-9e0f-2a8b1c4d5e6f
Idempotency-Key: create-task-7f3a91c2
Content-Type: application/json{
"type": "task",
"title": "Prepare the contract",
"fields": {
"priority": "high",
"due_date": "2026-10-01"
},
"relations": [
{"relation": "project", "object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b10"}
]
}Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Object type key or ID |
| string or | No | Title, up to 1000 characters |
| object | No | Field values, no more than 200 keys |
| UUID or | No | Assignee; defaults to the creator |
| array | No | Relations created together with the object, no more than 100 |
A relations item:
Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Relation type key or ID |
| UUID | Yes | The object on the other side |
|
| No | The new object's side; only needed for a relation of a type with itself |
| number or string | No | Position among the outgoing |
The object is created with the type's current schema version and enters the process's initial status. Empty fields get their default values. The response is 201 with the object.
Idempotency-Key is required. After a network error, retry with the same key and the same body: no second object is created, and you get the first response with the Idempotency-Replayed: true header. Use a new key only for a new object.
Reading and updating
GET /objects/{id} returns the whole object. The include parameter adds related objects: include=relations.project,relations.subtasks.
The version, status and field values in the response are read in a single database query and reflect the same moment: version always matches fields, even if the object is being changed while you read it. The same holds for each object in result sets. So you can safely pass the version from the response as expected_version.
PATCH /objects/{id} changes fields, the title and the assignee:
{
"expected_version": 28,
"set": {"priority": "critical"},
"unset": ["due_date"],
"title": "Prepare the contract by Friday",
"owner_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72"
}Field | Type | Required | Description |
|---|---|---|---|
| integer | Yes | The object version you read |
| object | No | New field values |
| array of keys | No | Fields to clear |
| string or | No | New title; |
| UUID or | No | New assignee — an active workspace member; |
set and unset together take no more than 200 keys. If nothing changed, the version does not increase and no events are sent.
Version conflict
If the object has changed in the meantime, the response is 409 OBJECT_VERSION_CONFLICT, with the current version in error.details. Re-read the object, apply your change to the new data and send it with the new version. Don't increment expected_version blindly.
What PATCH doesn't do
It doesn't change the status. A status key in
setreturns422 STATUS_CHANGE_REQUIRES_TRANSITION. The status changes only through a transition.It doesn't change relations. A relation field in
setis an error; relations have their own methods.It doesn't write to read-only fields —
422 FIELD_READONLY— or to fields missing from the object's schema version —422 FIELD_NOT_IN_SCHEMA_VERSION.It doesn't change an archived object —
409 OBJECT_ARCHIVED.
A violation of the type's rules (constraints) returns 422 CONSTRAINT_VIOLATION with a details.violations[] list: constraint_key, code, message.
Checklists
The value of a checklist field is a list of items:
[
{"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e10", "text": "Check the estimate", "done": true, "done_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72", "done_at": "2026-09-26T09:00:00Z", "rev": 31},
{"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e11", "text": "Send to the customer", "done": false, "done_by": null, "done_at": null, "rev": 30}
]An item's id is permanent. The server sets done_by and done_at itself when an item is checked. rev is the object version at which the item's text or check mark last changed.
You can pass the whole list in set of a PATCH /objects/{id} request: only text is required, items without an id get one (an item with the same text as an existing one keeps its id), and done_by, done_at and rev in the request are ignored.
Individual items are easier to change with POST /objects/{id}/checklists/{field} — this way two people checking different items at the same time don't overwrite each other:
{
"expected_version": 31,
"ops": [
{"op": "check", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e11", "done": true},
{"op": "add", "text": "Get the signature", "after": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e11"}
]
}Operations:
add(a new itemtext, optionallydone, your ownidandafter),check(doneof itemid),rename(newtext),remove,move(itemidafter itemafter;after: nullmoves it to the top). Up to 100 operations per request.If the object changed after
expected_version, the operations are still applied — unless an affected item itself changed after that version or was deleted: then you get409 OBJECT_VERSION_CONFLICTwithdetails.reasonitem_changedoritem_removedanddetails.item_id.addwith an existingidandremoveof a missing item do nothing, so retrying a request is safe.Permissions, read-only fields, constraints, history and events work as for
PATCH /objects/{id}with the new list inset. The response is the object, as for other changes.
Subtasks and "3/5" counters are described in Flow API: subtasks, checklists and recurrence.
Archive and restore
POST /objects/{id}/archive and POST /objects/{id}/restore take the body {"expected_version": 28}.
Archiving:
an archived object disappears from lists and result sets but stays in relations and history;
archiving again changes nothing and returns
200;if a relation type forbids deletion (
on_delete: restrict) and such relations exist —409 RELATION_RESTRICT;relations with
on_delete: cascadearchive the related objects. If there are more than 100 of them, the response is202withoperation_idandstatus_url: thecascade_archivebackground operation archives the rest;the object's timers (SLA, reminders) and running processes are cancelled.
Restoring:
the object's status doesn't change; the SLA of the current status resumes from the original entry time;
cancelled processes are not resumed automatically;
if the object's type or schema version has been retired —
409 OBJECT_TYPE_ARCHIVED.
History
GET /objects/{id}/history?page[size]=50 returns the object's changes, newest first:
{
"items": [
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c01",
"kind": "transition",
"action": "object.transition",
"actor": {"type": "user", "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72"},
"changes": null,
"request_id": "b3c1e7a2-0d4f-4a8e-9c61-5f2e8d7a1b90",
"correlation_id": null,
"occurred_at": "2026-09-16T10:00:00.000000Z",
"transition": {
"key": "win",
"from_state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b75", "key": "negotiation", "category": "in_progress"},
"to_state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71", "key": "won", "category": "done"},
"lifecycle_version_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b80",
"object_version": 28,
"reason": null
}
}
],
"page": {"size": 50, "next_cursor": null}
}kind—audit(a change) ortransition(a transition). Other kinds will appear later — skip the ones you don't know.action— for exampleobject.create,object.update,object.archive,relation.add,relation.remove,object.transition.changes— changes by key as{old, new}; a missing side means the key didn't exist.actor.type— who made the change:user(a person),service(a service member, such as a workspace key),automation,processorsystem. For automations and processes,on_behalf_ofshows on whose behalf they acted.System transitions:
$initial— object creation,$migration— a move to a new process version.
Changes to fields you cannot read are removed from the history. Relations with objects you cannot see are hidden.
Transitions
A transition is the only way to change an object's status:
POST /v1/objects/{id}/transitions/win
Idempotency-Key: win-deal-5521-1{
"expected_version": 28,
"form_values": {"lost_reason": null},
"reason": "The customer signed the contract"
}Field | Type | Required | Description |
|---|---|---|---|
| integer or | No | Without it, the object's current version is used |
| object | No | Values of the transition form fields ( |
| string or | No | A comment on the transition, up to 1000 characters, saved in the history |
Idempotency-Key is required. The response is the object after the transition, with transition_id.
Why a transition failed
A refusal is 422 TRANSITION_NOT_ALLOWED. error.details contains a full breakdown:
{
"transition": "start_production",
"allowed": false,
"from_state": "prototype",
"to_state": "ready_for_production",
"object_version": 27,
"reasons": [
{
"code": "GUARD_FAILED",
"message": "Prototype is not approved",
"rule_code": "PROTOTYPE_NOT_APPROVED",
"source": {"kind": "guard", "key": "prototype_approved"}
},
{
"code": "REQUIRED_FIELD_MISSING",
"message": "Field \"Batch size\" is empty",
"source": {"kind": "required_field", "field": "batch_size"}
}
],
"required_fields": [{"field": "batch_size", "present": false}],
"failed_guards": ["prototype_approved"],
"failed_constraints": []
}Reason codes (reasons[].code):
Code | Meaning |
|---|---|
| The object is archived |
| The type has no status process |
| No such transition in the object's process version |
| The transition doesn't start from the current status |
| No permission for this transition |
| A field required for the transition is empty |
| A transition condition isn't met; |
| A type constraint is violated |
| An expression failed to evaluate; details in |
New codes will appear — treat an unknown one as a general refusal. Other transition errors: 404 OBJECT_NOT_FOUND, 409 OBJECT_VERSION_CONFLICT, 403 PERMISSION_DENIED, form field errors (FIELD_READONLY, FIELD_NOT_IN_SCHEMA_VERSION, VALIDATION_FAILED) and 422 RELATED_SET_TOO_LARGE.
Available actions
To show a user only the buttons they can use, ask the server in advance.
GET /objects/{id}/available-actions — for one object:
{
"version": 27,
"transitions": [
{"key": "approve", "to_state": "approved", "allowed": true, "required_fields": []},
{
"key": "start_production",
"to_state": "ready_for_production",
"allowed": false,
"reasons": [{"code": "GUARD_FAILED", "message": "Prototype is not approved", "rule_code": "PROTOTYPE_NOT_APPROVED"}]
}
],
"actions": [
{"key": "send_to_review", "kind": "transition", "allowed": true}
]
}transitions— transitions from the current status.required_fieldslists the transition's required fields that are currently empty;reasonsappears only on unavailable ones.actions— enabled type actions (see below), checked the same way.version— the object version the response was computed for.
POST /objects/available-actions does the same for many objects — for example, all cards on a board:
{
"object_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71"],
"include": ["transitions"]
}Field | Type | Required | Description |
|---|---|---|---|
| array of UUIDs | Yes | 1 to 200 distinct IDs; more returns |
| array | No |
|
The response is {"items": {"<id>": {…}}}. For an object that doesn't exist or that you cannot see, you get {"error": {"code": "OBJECT_NOT_FOUND"}} instead of a result.
Both methods only read data and are computed without locks. The result is a hint: the command re-checks everything when it runs. These methods are available to a read-only key.
Object actions
An action is a configured button on top of an existing command. There are three kinds (kind):
| What it does |
|
|---|---|---|
| Performs a transition; the form shows some of its fields |
|
| Changes only the listed fields |
|
| Starts a process for the object |
|
config is limited to 16 KB; extra keys are rejected.
Configuring actions
GET /object-types/{type}/actions — all actions of the type, including disabled ones, sorted by position, then key. Requires permission to read the type's schema.
POST /object-types/{type}/actions creates an action (requires permission to manage the type's schema):
{
"key": "mark_urgent",
"label": "Urgent",
"kind": "update_fields",
"config": {"fields": ["priority"]},
"placement": ["detail", "list"],
"position": 10,
"enabled": true
}Field | Type | Required | Description |
|---|---|---|---|
| key | Yes | Unique within the type; a duplicate returns |
| string | Yes | Button label, 1–200 characters |
| string | Yes |
|
| object | Yes | Settings for the kind, see the table above |
| array | No | Where to show the button: for example |
| integer | No | Order, 0 by default |
| boolean | No |
|
config is validated against the type's current definitions: the transition must exist in the current process version, form_fields must be among the transition's form fields, and update_fields among the fields of the current schema. The start_process process is checked when the action is evaluated and run.
PATCH /object-actions/{id} changes label, config (as a whole), placement, position and enabled; key and kind cannot be changed. DELETE /object-actions/{id} deletes the action and returns it; a repeat returns 404.
Running an action
POST /objects/{id}/actions/{action_key}:
{"expected_version": 12, "fields": {"priority": "critical"}}Field | Type | When | Description |
|---|---|---|---|
| integer | Required for | Object version |
| object |
| Values: form fields for a transition, new values for an edit |
| array of keys | Only | Fields to clear |
| string | Only | A comment on the transition |
fields and unset together take up to 200 keys. The server checks in order: the object and permission to read it (404 OBJECT_NOT_FOUND), an enabled action with this key (404 NOT_FOUND), permission for the action (403 PERMISSION_DENIED), the fields (422 VALIDATION_FAILED, code not_an_action_field for a field outside the form). Then the command's own checks apply: a transition returns 422 TRANSITION_NOT_ALLOWED with reasons; start_process with an unavailable process returns 422 VALIDATION_FAILED (action_not_available), and you can find the started instance with GET /process-instances?object_id=. The response is the object after the action.
Relations
A relation connects two objects through a relation type: a task with a project, a deal with a company. A relation type has from and to sides, a cardinality and an archiving rule. Relation types are created in the schema — see Flow API: types, fields, statuses and publishing.
Direction
The direction parameter sets which side of the relation the object in the path is on:
outgoing— the object in the path isfrom;incoming— the object in the path isto.
Without direction, the side is chosen by the object's type; for a relation of a type with itself, it is outgoing. A wrong side returns 422 RELATION_TYPE_MISMATCH.
List
GET /objects/{id}/relations/{relation_key}?direction=outgoing&page[size]=50:
{
"relation_key": "subtasks",
"direction": "outgoing",
"items": [
{
"relation": {
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6d01",
"relation_type_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6d00",
"relation_key": "subtasks",
"from_object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"to_object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90",
"position": "1",
"created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"created_at": "2026-09-10T09:00:00.000000Z"
},
"object": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90", "title": "Approve the estimate", "type": "task", "archived_at": null}
}
],
"page": {"size": 50, "next_cursor": null}
}Relations are ordered by position. Objects you cannot read are skipped — a page may be shorter than page[size] while next_cursor is not null. Archived related objects are included with archived_at.
Adding
POST /objects/{id}/relations/{relation_key}:
{"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b90", "position": 2, "expected_version": 28}Field | Type | Required | Description |
|---|---|---|---|
| UUID | Yes | The object on the other side |
| number or string | No | Position among the outgoing |
| integer or | No | Version of the object in the path; only with |
The response is 201 if the relation was created, and 200 with "changed": false if it already existed. The response contains relation, changed and the current versions of both sides, from_version and to_version. You need permission to edit the objects on the sides whose version increases when the relation changes.
Removing
DELETE /objects/{id}/relations/{relation_key}/{object_id} always returns 200: changed: true with the removed relation, or changed: false and relation: null if there was no relation. Permissions are checked before the relation's existence, so a repeat without permission returns 403 again.
Relations of many objects
POST /objects/relations reads relations for many objects at once — for example, for all rows of a timeline:
{
"object_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70", "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b71"],
"relations": [{"key": "blocks", "direction": "outgoing"}],
"limit": 20
}Field | Type | Required | Description |
|---|---|---|---|
| array of UUIDs | Yes | 1 to 500 distinct IDs; more returns |
| array | Yes | 1 to 5 relation types: |
| integer | No | How many related objects to return per set, 1–50, 20 by default |
The response is {"items": [...]}, one set per "object — relation type" pair, ordered by object_ids, then relations: object_id, relation_key, direction, objects (id, title, type, archived_at) and more: true if there are more related objects than limit. Empty sets are not returned. Objects that don't exist, that you cannot see or that don't fit the relation side are silently skipped; so are related objects you cannot read. An unknown relation type returns 404 NOT_FOUND. The request only reads data; no Idempotency-Key is needed.
Relation errors
HTTP |
| Meaning |
|---|---|---|
404 |
| One of the objects doesn't exist or you cannot see it |
404 |
| No such relation type |
403 |
| No permission to edit the object |
409 |
| One of the objects is archived |
409 |
| The version of the object in the path has changed |
422 |
| The object doesn't fit the relation side |
422 |
| The relation violates cardinality, for example the task already has a project |
422 |
| The relation would create a cycle (for relation types without cycles) |
422 |
| The relation field is read-only |
422 |
| A type constraint is violated |
Files
An object's files are stored by Sensever Assets; Flow stores only their metadata. Uploading takes three steps.
Upload session.
POST /objects/{id}/attachments/uploadswith{"file_name": "estimate.pdf", "mime_type": "application/pdf", "size_bytes": 482133}. The name is up to 255 characters with no control characters or slashes;mime_typeis up to 127 characters, and if the type is unknown, useapplication/octet-stream. The response is201:upload_ticket,expires_atanduploadwith the fieldsprotocol(tus),endpoint,metadata,max_bytes.Uploading the bytes. Send the file to
upload.endpointover the tus 1.0 protocol, passingupload.metadatain theUpload-Metadataheader. The size must matchsize_bytesexactly.Confirmation.
POST /objects/{id}/attachmentswith{"upload_ticket": "…"}. The response is201with the attachment; a repeat with the same ticket returns200and the same attachment. The name comes from the ticket, and the type and size come from Assets, not from the client.
While Assets is checking the file, the confirmation returns 503 SERVICE_UNAVAILABLE with details.reason = attachment_processing and details.retry_after in seconds — try again later. An unfinished upload returns 422 with upload_incomplete; a rejected file (malicious or corrupted) returns 422 with file_rejected.
GET /objects/{id}/attachments returns the attachments (newest first) and the limits:
{
"items": [
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6e01",
"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
"file_name": "estimate.pdf",
"mime_type": "application/pdf",
"size_bytes": 482133,
"uploaded_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"created_at": "2026-09-16T10:05:00.000000Z",
"deleted_at": null
}
],
"archived": false,
"can_upload": true,
"limits": {"max_file_bytes": 2147483648, "max_per_object": 100, "max_file_name": 255}
}limits.max_per_object— how many files can be attached to the object; more returns422 LIMIT_EXCEEDED.limits.max_file_bytes— the largest file Storage accepts (the value in the example is illustrative); larger returns422 LIMIT_EXCEEDEDwithfile_too_large.A file takes up space in the workspace owner's personal Storage. If space runs out or there are too many unfinished uploads —
429 RATE_LIMITEDwithupload_quotaandRetry-After. If the workspace owners have no Sensever account —422 VALIDATION_FAILEDwithstorage_payer_missing.Attachments of an archived object are hidden:
archived: trueand an emptyitems.can_upload— whether you can upload: requires permission to edit the object.
GET /objects/{id}/attachments/{attachment_id}/download-url returns a signed url with expires_at — it lives for a few minutes. Don't store it: get a new one for every download.
DELETE /objects/{id}/attachments/{attachment_id} marks the attachment as deleted; Assets deletes the file. A repeat returns the already deleted attachment.
Uploading, confirming and deleting require permission to edit the object and don't work on an archived object (409 OBJECT_ARCHIVED). If files are disabled in the installation, the methods return 503 with details.reason = attachments_disabled.
Discussion
Comments on an object live in Sensever chat. POST /objects/{id}/discussion with the body {"origin": "https://sensever.com"} checks access to the object and issues a personal pass to the discussion:
{
"frame_url": "https://chat.sensever.com/comments/frame?…",
"chat_url": "https://sensever.com/?thread=901",
"visibility": "private",
"token": "cm1.…",
"expires_in": 90,
"can_write": true
}origin— the address of the page that shows the discussion: onlyhttps://sensever.comorhttps://flow.sensever.com.tokenlives no longer than 90 seconds. Refresh it ahead of time; don't store it or pass it in the page URL.chat_url— a link to the thread in chat;nulluntil the person joins the discussion by sending their first comment.can_write— whether the person can write: requires permission to edit the object, and the object must not be archived.
A discussion opens only on behalf of a person with a Sensever account — this method is for the interface, not for server integrations. Every call re-checks access; Idempotency-Key is ignored. When a person loses access to the object, Flow revokes their participation in the discussion.
Mentions
You can mention a person with @ in an object's description and comments. For how this looks in the interface, see Flow: mentions.
GET /objects/{id}/mention-candidates?q=ann — who can be mentioned: active workspace people who can currently read the object, sorted by name, no more than 8, excluding yourself. q is part of a name, case-insensitive, up to 100 characters; without q, everyone sorted by name. Requires permission to read the object, otherwise 404 OBJECT_NOT_FOUND.
{
"items": [
{"principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72", "display_name": "Anna Smith", "picture_url": "https://…"}
]
}display_name and picture_url are the name and photo from the Sensever account. picture_url is an https link, or null if there is no photo: show initials in that case.
GET /object-types/{type}/mention-candidates — the same for an object that doesn't exist yet (the create form): people who can read objects of this type. If you can't read them yourself — 404 NOT_FOUND.
Mentions in a text field
A mention in the description and other text fields is markup right inside the string value: [@Anna Smith](principal:0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72). Only the ID determines who is mentioned; the label is what the author saw. The value stays an ordinary string: history, CSV export and import, search and expressions see the markup as is.
When a person or an API key creates an object or changes a text field, each newly mentioned person (no more than 20 per change) gets a "You were mentioned" notification in the mentions category — if they can currently read the object and haven't turned that category off. The author of the change doesn't get a notification about themselves. Changes made by automations, processes and recurring tasks, as well as background operations with automation_mode: suppressed, don't create mention notifications.
Mentions in a comment
Call POST /objects/{id}/discussion/mentions before sending a comment with mentions:
{"principal_ids": ["0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72"]}principal_ids— 1 to 20 distinct members.Everyone who can currently read the object gets access to the discussion in chat, and the response contains a mention reference
ref(likep.123) that the interface embeds in the comment:{"items": [{"principal_id": "…", "ref": "p.123"}]}.People who can't read the object, are inactive or have never signed in to chat are not included in
items.The caller needs the same as for sending a comment: permission to edit the object and a non-archived object, otherwise
403 PERMISSION_DENIED. If chat is unavailable —503 SERVICE_UNAVAILABLE.A repeat doesn't add anyone twice;
Idempotency-Keyis ignored.
What's next
Flow API: query language and search — how to search for objects and read lists.
Flow API: subtasks, checklists and recurrence — subtasks, counters and recurring tasks.
Flow API: views, export, import and background operations — bulk changes and CSV.
Flow API: webhooks — how to find out about object changes.
Комментарийлер