Workspaces

A workspace is the tenant an inbox belongs to. Six tools; the write tools are restricted to system tokens, because a workspace is provisioned by the source system rather than by an end user.

See the Workspace model for the shape of the returned object.

---

workspaces_list

Read · scope inbox/workspaces · permission workspaces.list · GET /workspaces

List the workspaces of the token's organization. Cursor-paginated; returns { data, meta: { next_cursor } }.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
source	string	Filter by source system, e.g. kobana_app.
slug	string	Filter by slug.
external_id	string	Filter by the id in the source system.
created_at_gte	string	created_at on or after this ISO 8601 timestamp.
created_at_lte	string	created_at on or before this ISO 8601 timestamp.

workspaces_get

Read · scope inbox/workspaces · permission workspaces.show · GET /workspaces/{id}

Fetch one workspace by internal id or external_id.

Parameter	Type	Description
id required	string	Internal id or external_id.

workspaces_create

Write · scope inbox/workspaces + write · permission workspaces.create · POST /workspaces

Create a workspace. Requires a src=system token.

Parameter	Type	Description
label required	string	Display name, 1–120 chars.
external_id	string	Id of the record in the source system.
source	string	Source system, e.g. kobana_app.
slug	string	Lowercase, dasherized. Becomes a segment of every inbox address.
monthly_cost_limit	number | null	Monthly LLM cost ceiling.
monthly_emails_limit	integer | null	Monthly processed-e-mail ceiling.
custom_metadata	object	Free-form JSON owned by the caller.
idempotency_key	string	Replay guard, 8–255 chars.

workspaces_upsert

Write · scope inbox/workspaces + write · permission workspaces.create · PUT /workspaces

Create or update a workspace, matched by id then external_id. Answers 200 when updated, 201 when created. Requires a src=system token.

Parameter	Type	Description
id	string (uuid)	Match by internal id first.
label	string	Display name, 1–120 chars.
external_id	string	Match key in the source system.
source	string	Source system.
slug	string	Lowercase, dasherized.
monthly_cost_limit	number | null	Monthly cost ceiling.
monthly_emails_limit	integer | null	Monthly e-mail ceiling.
custom_metadata	object	Free-form JSON.
idempotency_key	string	Replay guard.

workspaces_update

Write · scope inbox/workspaces + write · permission workspaces.update · PATCH /workspaces/{id}

Update a workspace in place. Changing the limits requires a src=system token.

Parameter	Type	Description
id required	string	Internal id or external_id.
label	string	Display name, 1–120 chars.
external_id	string	Id in the source system.
source	string	Source system.
slug	string	Lowercase, dasherized.
monthly_cost_limit	number | null	Monthly cost ceiling.
monthly_emails_limit	integer | null	Monthly e-mail ceiling.
custom_metadata	object	Free-form JSON.

workspaces_delete

Destructive · scope inbox/workspaces + write · permission workspaces.delete · DELETE /workspaces/{id}

Soft-delete a workspace. Requires a src=system token.

Parameter	Type	Description
id required	string	Internal id or external_id.