API

Verified against docs/superpowers/specs/2026-09-15-p4-a-typed-http-api-openapi-webhooks.md §4.3; re-verified against the code at close-out.

The Botseon API is one HTTP surface, /api/v1, authenticated by an organisation API key that is bound to the admin who created it: every call runs as that person, under the same checks the app applies, so a script never reaches a row its person could not open.

The section has four groups and fourteen pages.

Getting started

• Make your first call — create a key, send one authenticated request, and read the answer.
• Authentication and keys — the header, the three scopes, the key endpoints and the platform key.
• Envelopes, errors, idempotency and paging — the shape every endpoint shares, and the OpenAPI document.

Resources

• Organisations — read and rename the organisation your key belongs to; create one with a platform key.
• Members and invitations — list members, change a role, invite and revoke.
• Bots — create a bot from a template or a full profile, read it, update it, delete it.
• Routines and triggers — a routine's instruction, its schedule and its event triggers.
• Memories — the typed claims a bot reads, at organisation or bot scope.
• Conversations and messages — read a thread and its messages.
• Runs — start a run, read its state and cancel it.
• Approvals — read what a bot is waiting for and answer it.
• Batch — up to fifty operations in one call, all of them or none.

Webhooks

• Webhooks — the two events, the signed delivery and the retry schedule.

Tools

• The TypeScript SDK and headless mode — the library and the command that sends a task and waits for the result.

What every page holds

An endpoint page has the same six parts, in the same order: what it does, which credential it needs, the request, the response, the errors it can return, and its rate limits. A page in Getting started or Tools that walks you through a job has the six parts of a task page instead: what it does for you, what to have ready, the steps, a worked example, what can go wrong, and where to go next.

What is not here

There is no api/errors page: the error envelope and the full code list live in Envelopes, errors, idempotency and paging, and each endpoint page repeats only the codes it can return. The API adds no verb the app does not have, and no credential other than the organisation API key and the operator's platform key.