Flow API: your first integration in 15 minutes

SENSEVER

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

9 daqiqa oʻqish

Flow API: your first integration in 15 minutes

In this article, you connect your server to Flow step by step: issue a key, read types and fields, create a task, find it with a query, move it to in progress and subscribe to changes. Examples use curl and TypeScript (Node.js 18+ with built-in fetch).

The main workspace Main works well for the examples: everyone who has opened Flow has it, and it already contains the "Task" type (task) with the statuses "New" (new), "In progress" (in_progress), "Done" (done), "Cancelled" (cancelled) and the fields "Description" (description), "Priority" (priority), "Deadline" (due_date) and "Watchers" (watchers). In another workspace, the keys of types, fields and transitions may differ — steps 2 and 3 show how to find them.

General API rules — base URLs, headers, errors and limits — are in Flow API: basics.

Step 1. Key and workspace

  1. Open Flow on sensever.com and go to the workspace you need. The workspace UUID is in the address bar: https://sensever.com/flow/w/<workspace UUID>/….

  2. Open Profile → API (https://sensever.com/profile/api). Enter a key name, choose "Read and write" in the Flow block and select the workspace. Click "Create key" and copy the ak1.… key — it will not be shown again.

  3. Save the key and the workspace in your server's environment variables:

export FLOW_KEY='ak1.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
export FLOW_WS='0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70'

The key acts on your behalf: in the workspace it can do exactly what you can.

Step 2. Check access and find the type

Read the workspace — it is the simplest request for checking a key:

curl -s https://flow.sensever.com/v1/workspace \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS"
{
  "id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b70",
  "name": "Main",
  "is_system": true,
  "plan": "free",
  "status": "active",
  "quotas": {
    "api_requests_per_minute": 6000,
    "api_principal_requests_per_minute": 1200,
    "queue.*.weight": 1,
    "queue.*.max_concurrency": 4,
    "queue.*.rate_per_minute": 600
  },
  "created_at": "2026-09-17T15:20:00Z",
  "updated_at": "2026-09-17T15:20:00Z"
}

GET /me will not work here: it works only in a browser session, and a key gets 401.

Now the list of types:

curl -s https://flow.sensever.com/v1/object-types \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS"

In items, find the type with "key": "task". Note its current_schema_version_id — the published schema version that new objects are created with.

Step 3. Read the fields

curl -s https://flow.sensever.com/v1/schema-versions/<current_schema_version_id> \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS"

The fields[] array in the response lists the type's fields: key, data_type, label, is_required, config (for enum, the options are in config.options). Field values are passed by key:

data_type

Value in JSON

string, text, enum

string; for enum, the option key, for example "high"

number, integer

number

money

{"amount": "125000.00", "currency": "EUR"}

boolean

true or false

date

"2026-10-20"

datetime

"2026-10-20T09:00:00Z"

multi_enum

array of option keys

principal, multi_principal

member UUID or array of UUIDs

json

object or array

Relation fields (relation) are set not with a value but with relations — see Flow API: objects, transitions and relations.

The type's statuses and transitions are returned by GET /object-types/task/lifecycle: states[] contains the status keys and categories (open, in_progress, done, cancelled).

Step 4. Create a task

Creating an object requires an Idempotency-Key. Generate it once and keep it: if the response doesn't arrive because of a network problem, repeat the request with the same key — the server returns the object already created instead of creating a second one.

curl -s https://flow.sensever.com/v1/objects \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48213-create-task" \
  -d '{
    "type": "task",
    "title": "Call the customer about order 48213",
    "fields": {
      "priority": "high",
      "due_date": "2026-09-30",
      "description": "Confirm the delivery address"
    }
  }'

Response 201:

{
  "id": "0190f3c3-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "type": "task",
  "title": "Call the customer about order 48213",
  "version": 1,
  "state": { "id": "…", "key": "new", "category": "open", "entered_at": "2026-09-25T08:00:00Z" },
  "created_by": "…",
  "owner_id": "…",
  "schema_version": 1,
  "lifecycle_version": 1,
  "fields": { "priority": "high", "due_date": "2026-09-30", "description": "Confirm the delivery address" },
  "omitted_fields": [],
  "created_at": "2026-09-25T08:00:00Z",
  "updated_at": "2026-09-25T08:00:00Z",
  "archived_at": null
}

The assignee (owner_id) is you by default. To assign another member, pass owner_id with their principal_id (the list is at GET /workspace/members). If a field value is invalid, the response is 422 VALIDATION_FAILED with the field path in details.fields[].field, for example fields.due_date.

Step 5. Find tasks with a query

A query is POST /objects/query with a condition in Query AST format. Let's find open high-priority tasks, sorted by the nearest due date:

curl -s https://flow.sensever.com/v1/objects/query \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "task",
    "where": {
      "and": [
        { "field": "priority", "op": "eq", "value": "high" },
        { "system": "state.category", "op": "in", "value": ["open", "in_progress"] }
      ]
    },
    "sort": [{ "field": "due_date", "dir": "asc" }],
    "page": { "size": 50 }
  }'

The response contains items (objects), page.next_cursor (the next page cursor or null) and meta.unindexed_fields. Operators, text search and cost limits are described in Flow API: query language and search.

Step 6. Move the task to in progress

A status changes only through a transition. First, find out which transitions are available:

curl -s https://flow.sensever.com/v1/objects/<id>/available-actions \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS"
{
  "version": 1,
  "transitions": [
    { "key": "start", "to_state": "in_progress", "allowed": true, "required_fields": [] },
    { "key": "complete", "to_state": "done", "allowed": true, "required_fields": [] },
    { "key": "cancel", "to_state": "cancelled", "allowed": true, "required_fields": [] }
  ],
  "actions": []
}

Run the start transition (the idempotency key is required here too):

curl -s -X POST https://flow.sensever.com/v1/objects/<id>/transitions/start \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48213-start" \
  -d '{ "expected_version": 1 }'

The response is the object in its new status with a transition_id. If the transition is not allowed right now, the response is 422 TRANSITION_NOT_ALLOWED with the reasons in details.reasons.

Step 7. Update fields

An update requires expected_version — the version you read. The version increased after the transition, so take it from the latest response:

curl -s -X PATCH https://flow.sensever.com/v1/objects/<id> \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -d '{ "expected_version": 2, "set": { "due_date": "2026-10-02" }, "unset": ["description"] }'

If someone changed the task in the meantime, the response is 409 OBJECT_VERSION_CONFLICT: re-read the object (GET /objects/{id}) and retry with the new version.

The same in TypeScript

A small wrapper around fetch: the key and workspace in headers, an Idempotency-Key for changes, and parsing of the error envelope.

import { randomUUID } from "node:crypto";

const BASE = "https://flow.sensever.com/v1";

class FlowError extends Error {
  constructor(public status: number, public code: string, public details: unknown, public requestId: string) {
    super(`${status} ${code}`);
  }
}

async function flow<T>(method: string, path: string, body?: unknown, idempotencyKey?: string): Promise<T> {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${process.env.FLOW_KEY}`,
    "X-Workspace-Id": process.env.FLOW_WS!,
    Accept: "application/json",
  };
  if (body !== undefined) headers["Content-Type"] = "application/json";
  if (method !== "GET") headers["Idempotency-Key"] = idempotencyKey ?? randomUUID();
  const res = await fetch(BASE + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
  const data = await res.json();
  if (!res.ok) {
    const e = data.error ?? {};
    throw new FlowError(res.status, e.code ?? "UNEXPECTED_RESPONSE", e.details, e.request_id ?? "");
  }
  return data as T;
}

// The idempotency key is created once per action and reused on retry.
const createKey = randomUUID();
const task = await flow<{ id: string; version: number }>("POST", "/objects", {
  type: "task",
  title: "Call the customer about order 48213",
  fields: { priority: "high", due_date: "2026-09-30" },
}, createKey);

const started = await flow<{ version: number }>("POST", `/objects/${task.id}/transitions/start`, {
  expected_version: task.version,
});

const page = await flow<{ items: unknown[]; page: { next_cursor: string | null } }>("POST", "/objects/query", {
  type: "task",
  where: { system: "state.category", op: "eq", value: "in_progress" },
  page: { size: 50 },
});
console.log(started.version, page.items.length);

A query is also a POST, but it doesn't need an Idempotency-Key: queries don't use it and ignore it, so the wrapper can always send one.

Flow has a typed client, @sensever/flow-client, generated from the API contract (createFlowClient({ baseUrl, token, workspaceId, preferMinimal })) — the Flow interface uses it. It is not published to npm yet, so the examples in these articles use plain fetch.

Step 8. Get notified of changes: webhook

Instead of polling the API, subscribe your HTTPS endpoint to events. You need "Read and write" access and the permission to manage integrations in the workspace (owners and admins have it):

curl -s https://flow.sensever.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer $FLOW_KEY" \
  -H "X-Workspace-Id: $FLOW_WS" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/flow/events",
    "event_types": ["object.created", "object.updated", "object.status_changed"],
    "filter": { "type": "task" }
  }'

The secret (whsec_…) in the response is the signing secret. It is shown only once: save it and use it to verify the signature of every delivery (the Webhook-Signature header). The event format, signature verification with sample code, and retries are covered in Flow API: webhooks.

What's next

Izohlar

Mualliflar