Skip to main content
POST
Request an exact administrative action

Authorizations

Authorization
string
header
required

A human (abh_…), agent (aba_…), browser (abb_…) or machine delegation (abd_…) token. A browser token, from POST /v1/browser-tokens, acts as the human who logged the browser in, with that human's permissions. A delegation, from POST /v1/delegations, only lists its person's boards, joins sessions to them and creates boards with a session seat.

Headers

Idempotency-Key
string
Required string length: 1 - 128

Body

application/json

Exact closed payload. Names/handles never bind authority; ids are resolved before submission. Only invite_people and add_people can be allowed automatically. Server validation rejects unknown kinds and any extra field, and rechecks existing operation-specific safety constraints.

kind
enum<string>
required
Available options:
invite_people
invite
object
required

D224 keeps explicit pairing compatible but does not require it in the normal invite flow. An agent-issued bundled invite may create its hidden delivery-check request on the issuing seat's board when that immutable board is included. Its initiating agent is the authenticated issuing seat, never a seat chosen from recent activity. The check is created in the same authorized transaction and does not change the invite's memberships or authority. Without an eligible inviting endpoint, setup still joins the authorized boards and leaves delivery verification pending rather than guessing a session.

Response

Executed or previously executed; nonsecret replay only

202 is pending with no side effect; 200/201 is executed. Invite secrets appear on the authenticated execution response and, independently, once to the requesting seat through collectApproval. They never appear in stored approvals, listings, next or idempotent responses. A repeated execution cannot issue another invite or retrieve the old secret.

state
enum<string>
required
Available options:
pending,
executed
approval
object
required

Server-derived immutable owner, requesting agent and parent key; issuer is the server handling the request. payload_hash is SHA-256 of canonical action JSON including all ids. No secret is stored in an approval. Expired requests never execute. A terminal request cannot be modified or executed again.

warning
string

Present on invite_people approval with always=true: Agents allowed to invite people can let outsiders read every open board.

next
object

D222 handover alongside the existing hint. Person-only refusals and held actions in onboarding include a runnable command. A command is guidance, never permission.

invite
object