Flow API: objects, transitions and relations

SENSEVER

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

27 min read

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

POST /objects

A new object of a type; Idempotency-Key is required

Get an object

GET /objects/{id}

The object with the fields you are allowed to read

Update an object

PATCH /objects/{id}

Fields, title, assignee; requires expected_version

Archive

POST /objects/{id}/archive

Move the object to the archive

Restore

POST /objects/{id}/restore

Bring the object back from the archive

History

GET /objects/{id}/history

Changes, relations and transitions, newest first

Available actions

GET /objects/{id}/available-actions

Which transitions and actions are available to you right now

Available actions in bulk

POST /objects/available-actions

The same for 200 objects at a time

Perform a transition

POST /objects/{id}/transitions/{transition_key}

Change the status; Idempotency-Key is required

Type actions

GET /object-types/{type}/actions

Action buttons configured for the type

Create an action

POST /object-types/{type}/actions

A new button on top of a transition, field edits or a process

Update an action

PATCH /object-actions/{id}

Label, configuration, placement, order, on/off switch

Delete an action

DELETE /object-actions/{id}

Delete the action

Run an action

POST /objects/{id}/actions/{action_key}

Run the action's command

Related objects

GET /objects/{id}/relations/{relation_key}

List of relations of one type

Add a relation

POST /objects/{id}/relations/{relation_key}

Link to another object

Remove a relation

DELETE /objects/{id}/relations/{relation_key}/{object_id}

Break the relation

Relations of many objects

POST /objects/relations

Related objects for 500 objects at a time

Checklist items

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

Add, check, rename, reorder and delete items

Files

GET /objects/{id}/attachments

The object's attachments and limits

Start an upload

POST /objects/{id}/attachments/uploads

A file upload session in Sensever Assets

Confirm an upload

POST /objects/{id}/attachments

Record the uploaded file as an attachment

File link

GET /objects/{id}/attachments/{attachment_id}/download-url

A short-lived download link

Delete a file

DELETE /objects/{id}/attachments/{attachment_id}

Delete the attachment

Discussion

POST /objects/{id}/discussion

Access to the object's discussion in Sensever chat

Who can be mentioned

GET /objects/{id}/mention-candidates

People who can see the object, for an @mention

Who can be mentioned in a new object

GET /object-types/{type}/mention-candidates

The same for the create form

Admit mentioned people

POST /objects/{id}/discussion/mentions

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

id

UUID

Object ID

type

string

Object type key, for example task or deal

title

string or null

Title

version

integer

Object version; increases with every change, including relation changes if the relation type bumps the version

state

object or null

Current status: id, key, category (open, in_progress, done, cancelled) and entered_at — when the object entered this status. null for types without a process

owner_id

UUID or null

Assignee (the principal of a workspace member)

created_by

UUID

Who created the object

schema_version

integer

The field schema version the object follows

lifecycle_version

integer or null

Version of the object's status process

fields

object

Field values by key. Fields you cannot read and relation fields are not included

relations

object

Only when requested with include=relations.<key>: related objects {id, title} by relation key

created_at, updated_at

time

Creation and last change

archived_at

time or null

When the object was archived

Field values

The value format depends on the field type:

Field type

JSON value

string, text

String; string — up to 1 KB, text — up to 100 KB

number

Number

integer

Integer

money

{"amount": "150000.00", "currency": "EUR"} — amount as a string, ISO 4217 currency

boolean

true or false

date

"2026-09-30"

datetime

"2026-09-30T15:00:00Z" — RFC 3339

enum

Option key

multi_enum

Array of option keys

principal

Member UUID

multi_principal

Array of member UUIDs — for example, watchers

json

Any JSON up to 64 KB

checklist

Array of items {"id", "text", "done", "done_by", "done_at", "rev"}, up to 100 items, text 1–500 characters. See "Checklists"

tags

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

relation

Not passed in fields: relations are changed through relations

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 with GET /objects/{id};

  • include is 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

type

string

Yes

Object type key or ID

title

string or null

No

Title, up to 1000 characters

fields

object

No

Field values, no more than 200 keys

owner_id

UUID or null

No

Assignee; defaults to the creator

relations

array

No

Relations created together with the object, no more than 100

A relations item:

Field

Type

Required

Description

relation

string

Yes

Relation type key or ID

object_id

UUID

Yes

The object on the other side

side

from or to

No

The new object's side; only needed for a relation of a type with itself

position

number or string

No

Position among the outgoing from relations

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

expected_version

integer

Yes

The object version you read

set

object

No

New field values

unset

array of keys

No

Fields to clear

title

string or null

No

New title; null keeps the current one

owner_id

UUID or null

No

New assignee — an active workspace member; null keeps the current one. Requires permission to edit the object

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 set returns 422 STATUS_CHANGE_REQUIRES_TRANSITION. The status changes only through a transition.

  • It doesn't change relations. A relation field in set is 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 item text, optionally done, your own id and after), check (done of item id), rename (new text), remove, move (item id after item after; after: null moves 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 get 409 OBJECT_VERSION_CONFLICT with details.reason item_changed or item_removed and details.item_id.

  • add with an existing id and remove of 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 in set. 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: cascade archive the related objects. If there are more than 100 of them, the response is 202 with operation_id and status_url: the cascade_archive background 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) or transition (a transition). Other kinds will appear later — skip the ones you don't know.

  • action — for example object.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, process or system. For automations and processes, on_behalf_of shows 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

expected_version

integer or null

No

Without it, the object's current version is used

form_values

object

No

Values of the transition form fields (form_fields), up to 200 keys. A field outside the form returns 422 VALIDATION_FAILED with the code not_a_form_field

reason

string or null

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

OBJECT_ARCHIVED

The object is archived

NO_LIFECYCLE

The type has no status process

TRANSITION_NOT_FOUND

No such transition in the object's process version

TRANSITION_NOT_FROM_STATE

The transition doesn't start from the current status

PERMISSION_DENIED

No permission for this transition

REQUIRED_FIELD_MISSING

A field required for the transition is empty

GUARD_FAILED

A transition condition isn't met; rule_code is set by the condition's author

CONSTRAINT_VIOLATION

A type constraint is violated

EXPRESSION_ERROR

An expression failed to evaluate; details in error

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_fields lists the transition's required fields that are currently empty; reasons appears 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

object_ids

array of UUIDs

Yes

1 to 200 distinct IDs; more returns 422 LIMIT_EXCEEDED

include

array

No

transitions, actions or both; both by default

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):

kind

What it does

config

transition

Performs a transition; the form shows some of its fields

{"transition": "win", "form_fields": ["lost_reason"]}

update_fields

Changes only the listed fields

{"fields": ["priority", "due_date"]} — 1 to 200 fields, not read-only

start_process

Starts a process for the object

{"process_key": "approval", "input": {}}

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

key

Yes

Unique within the type; a duplicate returns 422 VALIDATION_FAILED (duplicate_key)

label

string

Yes

Button label, 1–200 characters

kind

string

Yes

transition, update_fields or start_process

config

object

Yes

Settings for the kind, see the table above

placement

array

No

Where to show the button: for example detail, list, board; 1–10 values

position

integer

No

Order, 0 by default

enabled

boolean

No

true by default

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

expected_version

integer

Required for update_fields, optional for transition

Object version

fields

object

transition, update_fields

Values: form fields for a transition, new values for an edit

unset

array of keys

Only update_fields

Fields to clear

reason

string

Only transition

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 is from;

  • incoming — the object in the path is to.

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

object_id

UUID

Yes

The object on the other side

position

number or string

No

Position among the outgoing from relations; at the end by default

expected_version

integer or null

No

Version of the object in the path; only with outgoing

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

object_ids

array of UUIDs

Yes

1 to 500 distinct IDs; more returns 422 LIMIT_EXCEEDED

relations

array

Yes

1 to 5 relation types: key — key or ID, direction — the side of the listed objects, as in GET /objects/{id}/relations/{relation_key}

limit

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

error.code

Meaning

404

OBJECT_NOT_FOUND

One of the objects doesn't exist or you cannot see it

404

NOT_FOUND

No such relation type

403

PERMISSION_DENIED

No permission to edit the object

409

OBJECT_ARCHIVED

One of the objects is archived

409

OBJECT_VERSION_CONFLICT

The version of the object in the path has changed

422

RELATION_TYPE_MISMATCH

The object doesn't fit the relation side

422

RELATION_CARDINALITY_VIOLATION

The relation violates cardinality, for example the task already has a project

422

RELATION_CYCLE

The relation would create a cycle (for relation types without cycles)

422

FIELD_READONLY

The relation field is read-only

422

CONSTRAINT_VIOLATION

A type constraint is violated

Files

An object's files are stored by Sensever Assets; Flow stores only their metadata. Uploading takes three steps.

  1. Upload session. POST /objects/{id}/attachments/uploads with {"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_type is up to 127 characters, and if the type is unknown, use application/octet-stream. The response is 201: upload_ticket, expires_at and upload with the fields protocol (tus), endpoint, metadata, max_bytes.

  2. Uploading the bytes. Send the file to upload.endpoint over the tus 1.0 protocol, passing upload.metadata in the Upload-Metadata header. The size must match size_bytes exactly.

  3. Confirmation. POST /objects/{id}/attachments with {"upload_ticket": "…"}. The response is 201 with the attachment; a repeat with the same ticket returns 200 and 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 returns 422 LIMIT_EXCEEDED.

  • limits.max_file_bytes — the largest file Storage accepts (the value in the example is illustrative); larger returns 422 LIMIT_EXCEEDED with file_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_LIMITED with upload_quota and Retry-After. If the workspace owners have no Sensever account — 422 VALIDATION_FAILED with storage_payer_missing.

  • Attachments of an archived object are hidden: archived: true and an empty items.

  • 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: only https://sensever.com or https://flow.sensever.com.

  • token lives 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; null until 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 (like p.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-Key is ignored.

What's next

Comments

Authors