# Workspace and flows

Orient the app: who it is, what it may do, the workspace’s stages, and what changed.

Start a session with `soontra_workspace_getContext`: it says which workspace the credential is for, which scopes it has and which tools it can call.

### soontra_flows_list

List the workspace flows (Kanban boards) with their pipeline stages ({ id, label, order_index }). Projects carry flow_id and a status matching a stage - use this to be board-aware before listing or creating projects.

Scope: `read` · Read-only

Takes no parameters.

Returns: Every flow with its `id`, `name` and `stages` (`id`, `label`, `color`, `order_index`), plus `count`.

### soontra_workspace_changes

Pull-based change feed (there is no push): commit-ordered canonical events after a cursor ({ since?, limit? } -> { status, reset_required, changes: [{ domain: workspace|projects|posts|files|comments, id, label: string|null, change: created|updated|deleted|purge|resync, updated_at }], next_cursor, has_more }). Store next_cursor and pass it back verbatim as since; a plain ISO timestamp also works as a race-free bootstrap cutoff. On purge, discard cached workspace state before refetching actor-visible lists; on resync, refetch the named file or workspace scope. Deletes, grant revokes, Personal gate changes, file moves, and ownership transfers are represented. Never includes WHO made a change.

Scope: `read` · Read-only

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | string | no | 1 to 200 characters |
| `limit` | integer | no | 1 to 100 |

Returns: A page of `changes` (`domain`, `id`, `label`, `change`, `updated_at`) with `status`, `reset_required`, `next_cursor` and `has_more`.

- `limit` defaults to 50, maximum 100.

- Paging works: pass `next_cursor` back as `since` until `has_more` is false.

- When `status` is `purge`, `reset_required` is true: drop cached workspace state and read the lists again.

### soontra_workspace_getContext

Call this FIRST in a session. Returns the workspace name, your role, member count, flows, and every social account grouped by platform across YouTube, Instagram, TikTok, LinkedIn, and X. Locked accounts remain visible but unavailable. Identify an account by its account_label; if an analytics call is ambiguous it returns selection_required with machine-readable choices carrying the account_id to pass back. Also returns granted_scopes and available_tools.

Scope: `read` · Read-only

Takes no parameters.

Returns: The `workspace_name`, `your_role`, `member_count`, `flows` and `connections` per platform, plus `granted_scopes` and `available_tools`.

- Accounts are listed by `account_label` only; an `account_id` comes from the `selection_required` answer of an analytics tool.

- `available_tools` leaves out the two tools that only interactive views call.

### soontra_flows_createStage

Add a board column (workflow stage) ({ label, color?, flow_id? }). ADMIN/OWNER credentials only - this reshapes every member's board. Defaults to the workspace's main flow when flow_id is omitted.

Scope: `write` · Writes · Owner or admin credential only

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes | 1 to 64 characters |
| `color` | string | no | 1 to 32 characters |
| `flow_id` | string | no | 1 to 64 characters |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The new `stage` with its `id`, `label`, `color`, `order_index` and `flow_id`.

- `label` is up to 64 characters; the stage id is a slug made from it.

### soontra_flows_updateStage

Rename or recolor a board column ({ stage_id, label?, color? }). ADMIN/OWNER credentials only. stage_id is the slug id from flows.list, not a uuid.

Scope: `write` · Writes · Owner or admin credential only

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `stage_id` | string | yes | 1 to 80 characters |
| `label` | string | no | 1 to 64 characters |
| `color` | string | no | 1 to 32 characters |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The updated `stage` with its `id`, `label`, `color`, `order_index` and `flow_id`.

- Pass `label`, `color` or both; a call with neither is refused.