Skip to content
Token Controller Docs
Docs / API / Organization and people

Organization and people

One organization is one event log, one cutoff and one reporting currency. These endpoints are what an org manager and a people manager use to run it; most of them are made by a person in the web app, not by a token.

Endpoint What it does Who
GET /organization, PATCH /organization The settings; change them. Anyone; org manager, in the web app
GET /organization/member-limit The member count and the plan's limit. Anyone
GET /members Everyone in the organization. Anyone
POST /members Invite someone by email. Org manager, in the web app
PATCH /members/{id}, DELETE /members/{id} Change a member's name, email, role or filters; remove a member. Org manager, in the web app
PUT /members/{id}/filters The filters a people manager's role is granted on. Org manager, in the web app
POST /members/{id}/invite Send the invite mail again. Org manager, in the web app
GET /grants, POST /grants The grants in force; hand a capability to someone for a filter inside your own. Anyone sees their own; grant on the filter, in the web app
GET /cutoff, POST /cutoff The cutoff; move it. Anyone; org manager, in the web app
GET /submissions, POST /submissions Submissions you may see; submit your messages since your last submit. Anyone, for themselves
POST /submissions/{id}/approve, /reject Approve, or reject with a reason. Approve on a filter its messages are in, in the web app
GET /submit-requests, POST /submit-requests The open requests to submit; ask everyone to submit by a day. Anyone; org manager, in the web app
GET /api-tokens, POST /api-tokens, DELETE /api-tokens/{id} Your tokens; create one; revoke one. Anyone for their own, in the web app
POST /api-tokens/{id}/hand-over Move a service token to another member. Its owner or an org manager, in the web app
GET /price-table, POST /price-table/rows The rows in force; add a row of your own or a contract's own price. Anyone; org manager, in the web app
POST /reversals Reverse any event by id. Whoever recorded it, whoever holds its capability on its filter, or an org manager

Organization

{
"id": "6b657374-0000-4000-8000-000000000001",
"name": "Kestrel Digital",
"slug": "kestrel",
"reporting_currency": "USD",
"approval": true,
"sign_in_domains": ["kestrel.example"],
"keep_content_text": false,
"cutoff": "2026-02-28",
"created_at": "2026-02-01T08:50:00Z"
}

PATCH /organization takes any of name, reporting_currency, approval, sign_in_domains and keep_content_text; fields left out stay. keep_content_text (default false) keeps prompts, responses, tool output and file contents in the received records; the log never holds them, and no screen shows them. approval says whether submissions need approval. sign_in_domains limits magic-link sign-in to these email domains; empty means any. slug is used in invite links. cutoff is the cutoff in force, null until one is set. See Organization settings.

GET /organization/member-limit answers {"members": 5, "member_limit": 150, "message": null}; members counts everyone invited or joined who has not left, member_limit is null where there is none, as on the open edition, and message is what an invite past the limit is refused with. See Plans and limits.

Members

POST /api/v1/members
{ "name": "Mara Lind", "email": "mara@kestrel.example", "role": "agent_manager", "attributes": { "team": "web" } }

role is agent_manager (the default), people_manager or org_manager; a people manager also takes filters, at least one, the filters their role is granted on, such as [{"team": "web"}]. 201:

{
"member": {
"id": "7f1c4e2a-…",
"email": "mara@kestrel.example",
"name": "Mara Lind",
"role": "agent_manager",
"attributes": { "team": "web" },
"filters": [],
"status": "invited",
"invited_at": "2026-02-01T09:20:00Z",
"joined_at": null
},
"invite_url": "https://app.tokencontroller.com/i/kestrel-4f2a9c1e7b03"
}

The person gets the link by mail; tc connect takes it too. 409 when the address is already a member or the member limit is reached. GET /members lists everyone in the member shape; status is invited, joined or removed, and attributes are theirs today. PATCH /members/{id} changes name, email, role or filters; a new role or new filters replace the grants the old ones gave. DELETE /members/{id} removes a member: they can no longer sign in, their past messages keep them as their person, and their service tokens wait for a new owner. 409 when the organization would have no org manager left.

Grants

A grant is (person, capability, filter). Roles give grants too; POST /grants hands one out by itself.

POST /api/v1/grants
{ "person": "tom@kestrel.example", "capability": "view", "filter": { "client": "acme" } }

capability is view, assign, approve, plan or grant; record is everyone's, and adjust belongs to org managers. The filter must lie inside one you hold grant on. 201:

{
"id": "grt_41ab…",
"person": "tom@kestrel.example",
"capability": "view",
"filter": { "client": "acme" },
"from_role": false,
"recorded_at": "2026-03-02T10:00:00Z"
}

A new grant for the same person and capability supersedes the old one; reversing the id takes it away. GET /grants lists the grants in force: everyone sees their own, whoever holds grant on a filter sees the grants inside it, org managers see all. person=tom@kestrel.example keeps one person's. See Grants and roles.

Cutoff

{
"cutoff": "2026-02-28",
"frozen_as_of": "2026-02-28T00:00:00Z",
"event_id": "cut_8e7d…",
"moved_by": "nadia@kestrel.example",
"moved_at": "2026-03-03T08:00:00Z"
}

cutoff is null when none was set: every figure is live. POST /cutoff with {"cutoff": "2026-03-31"} moves it; moving it back is allowed, and a day after today gets 400. Figures as of the cutoff never change on their own; events dated before it need adjust. A rule or a contract assignment may still set a contract on messages before it, since figures as of the cutoff stay as they were. See Cutoff.

Submissions

A submit is a person confirming their own messages since their last submit, up to a day.

POST /api/v1/submissions
{ "to": "2026-03-31" }

to defaults to today and cannot be later. 201, here Mara's first submit, which starts at her first message:

{
"id": "sub_2d9e…",
"person": "mara@kestrel.example",
"from": "2026-03-04",
"to": "2026-03-31",
"status": "submitted",
"reason": null,
"messages": 2,
"cost": "700.00"
}

An empty submit says there was nothing to add. 409 when you already submitted up to that day. GET /submissions lists your own and those with messages inside a filter you view; person= keeps one person's. POST /submissions/{id}/approve, and /reject with {"reason": "wrong client"}, set status to approved or rejected; a rejected submission goes back to its person's review list, and its days are open to submit again. Approving needs approve on a filter the messages are in, never your own. See Submit.

POST /submit-requests with {"until": "2026-04-03", "message": "March figures go to finance on Friday"} asks everyone to submit by a day; each person who has not submitted gets one email. GET /submit-requests lists the open requests with id, requested_by, requested_at, until, message and done, whether you have submitted up to the request's day.

API tokens

POST /api/v1/api-tokens
{ "kind": "service", "name": "review bot" }

kind is service, read or organization; anyone creates service and read tokens for themselves, only an org manager the organization token. 201, the only time the secret is shown:

{
"id": "3d0a9c51-…",
"kind": "service",
"name": "review bot",
"shown_prefix": "tc_svc_3f9a",
"person_id": "9b4d…",
"needs_owner": false,
"created_at": "2026-02-10T11:00:00Z",
"last_used_at": null,
"token": "tc_svc_3f9a…"
}

GET /api-tokens lists your tokens without their secrets, or every token in the organization for an org manager, CLI tokens (kind: "cli") included. needs_owner is set when the person left: the token's entries show as an error until POST /api-tokens/{id}/hand-over with {"person_id": "…"} gives it a new owner, and only future entries follow. DELETE /api-tokens/{id} revokes a token, 204. See The person of a message.

Price table

GET /api/v1/price-table?provider=anthropic&model=claude-sonnet-4-5&as_of=2026-03-31
{
"as_of": "2026-03-31T23:59:59.999999999Z",
"rows": [
{
"id": "prc_5f6a…",
"provider": "anthropic",
"model": "claude-sonnet-4-5",
"kind": "input",
"price_per_million": "10",
"valid_from": "2026-01-01",
"source": "organization",
"contract": null,
"recorded_at": "2026-02-01T09:00:00Z"
}
]
}

The example organization prices each of its models with one row of its own, so the worked month costs the same on every instance. Rows are sorted by provider, model, valid_from and kind. source is managed (ids prm_…) or organization (ids prc_…); the organization's row wins over a managed row with the same provider, model, kind and valid_from. price_per_million is in US dollars, written in full without trailing zeros, such as "0.3". contract names the contract whose own price this is: such a row counts for that contract's messages only and wins over every other row there.

POST /price-table/rows takes provider, model, kind, price_per_million and valid_from, and optionally contract:

POST /api/v1/price-table/rows
{ "provider": "anthropic", "model": "claude-sonnet-4-5", "kind": "input", "price_per_million": "9", "valid_from": "2026-04-01", "contract": "anthropic-api" }

provider is one the price table names rows under: anthropic, openai, google, aws_bedrock, gcp_vertex, azure_foundry, github, cursor or other. kind is any token kind, such as input, output, cache_read, cache_write, cache_write_5m, cache_write_1h or reasoning. contract must be a contract on record with the same provider. 201 with the row; 409 when the same row is already in force. A wrong row is reversed by its id; managed rows cannot be reversed. The columns are on Price tables.

Reversals

POST /api/v1/reversals
{ "event_id": "spl_0c3a…" }

201 with id, the reversal's own event id (rev_…), and event_id. The event stays in the log and stops counting; a reversed split leaves the earlier split, or the rules, in force again, and a reversed contract assignment lets the message find its contract again. dated dates the reversal; before the cutoff that needs adjust. 409 when the event is already reversed, for a reversal itself (record the event again instead), and for a managed price row. Whoever recorded the event, whoever holds the capability it took on its filter, or an org manager may reverse it; a service token may reverse what it recorded. A saved report is removed the same way, by its rpt_… id; the answer then gives that id as both id and event_id.

Last updated 16 November 2026 · Edit this page© 2026 Jan Beck · Privacy · Imprint