api/openapi.yaml is the REST API every client is generated from and every check reads: the app's
client (Orval), the breaking-change check (oasdiff), the lint (bun run api:lint) and the server's
contract tests. It is a bundle. Never edit it by hand: edit its sources and bundle.
The sources live in api/openapi/, one file per area, so builders working on different areas do
not touch the same lines:
| File | What it holds |
|---|---|
common.yaml |
The root: info, servers, tags, security schemes and OAuth scopes, the list of paths, and what every area shares (problem details, paging, Idempotency-Key, shared headers and responses) |
bots.yaml |
Bots |
audit-events.yaml |
The audit trail |
accounts.yaml |
People, API keys, sessions, linked accounts and identity providers |
admin-settings.yaml |
Deployment, organization settings, capabilities, network policies, model usage, computer actions and the setup checklist |
conversations.yaml |
Conversations and their members, messages and attachments, tasks, reactions, dictation, voice calls, conversation join tokens and product events |
model-connections.yaml |
The vault, the model key, the model catalogue and model choices |
notifications.yaml |
Devices, destinations, deliveries and notification settings |
components.yaml |
The components a Bot draws, their drafts and publishing, their data functions, and which a Bot may use |
skills.yaml |
Skills |
apps.yaml |
The apps added to OpenBot, the app directory, app setup and each app's account mode and OAuth client |
connections.yaml |
A person's connections to apps and their accounts, and an app's shared connection |
bot-grants.yaml |
What a Bot was given: its grants and apps, giving and taking back an app, and app access requests |
schedules.yaml |
Routines, check-ins and what they found, goals with their triggers and GitHub event sources, and a Bot's follow-ups |
approvals.yaml |
Approvals and questions, approval rules and settings, reviewer guidance, boundaries, what-if, shared app accounts and folder access |
organizations.yaml |
The organizations a person is a member of, and each one's members |
computers.yaml |
A Bot's computer: its state, screen, control, a Bot's actions on it, its files, and the administrator's list |
browsers.yaml |
A Bot's browser and a person's own OpenBot browser |
passwords-and-recorder.yaml |
Sign-in requests, saved logins and the Recorder |
learning.yaml |
OpenBot's side of Automatic learning: Learning settings, each person's spaces and sharing choices, sharing requests, and the skills delivered to Bots |
memory.yaml |
A person's memories and memory sources |
An area file holds its operations under paths, and under components the schemas, parameters,
responses and examples only it uses. Inside the file, refer to them as usual
('#/components/schemas/Bot'); refer to a shared one in common.yaml
('./common.yaml#/components/responses/Unauthenticated'). The bundle names every component after
its own key, so pick a name no other area uses; a clash fails the bundle.
common.yaml lists each path once, as a $ref into its area file. A new component needs no line
there; the ones listed as $refs into area files are listed only to keep the bundle's order. Keep
each tag, scope and path in common.yaml on one line, so a merge keeps every entry whole.
- Edit the area file (and, for a new path, tag or scope, append one line to
common.yaml). - Run
bun run api:generate. It bundlesapi/openapi.yamlfirst, then regenerates the client. - Commit the sources,
api/openapi.yamlandapp/src/lib/api/generatedtogether.
After a rebase, run bun run api:bundle and bun run api:generate again and commit what changed.
common.yaml, api/openapi.yaml and the generated client's index files merge with git's union
driver (.gitattributes), which keeps both sides' appended lines instead of stopping on a
conflict; the bundle and the client are rebuilt from the merged sources, and CI's drift checks
(the bundle matches its sources, the client matches the bundle) catch anything the merge got
wrong. If both sides changed the same line of common.yaml, union keeps both: delete the stale
one.
The API spec job in .github/workflows/ci.yml fails a pull request when:
api/openapi.yamlis not what its sources bundle to, orapp/src/lib/api/generatedis not what it generates;bun run api:lintfails. It runs Redocly's strict rules and OpenBot's conventions (redocly.yaml,api/redocly/rules.mjs): OpenAPI 3.1, every path under/api/v2/organizations/{organizationId}/, no path CopilotKit Intelligence already serves (api/intelligence-reserved.yaml), errors asapplication/problem+json, anIdempotency-Keyon every write, andcursorandlimiton every list;- the spec breaks a client of the base branch's spec (oasdiff). A change that takes nothing from a client goes through only when it is listed with its reason in accepted-breaking-changes.md.
api/asyncapi.yaml (AsyncAPI 3.1) describes every WebSocket: a Bot's run as it streams, what
changed in a person's conversations, a Bot's screen and terminal, a voice call, and what the
Recorder captures. It is one file, edited by hand, and bun run api:lint lints it with the REST
spec. CI compares it with the base branch's (bun run api:live:diff <base file> api/asyncapi.yaml;
api/asyncapi-diff.ts says what counts as breaking), and
accepted-live-breaking-changes.md lists the changes let
through.
- Create
api/openapi/<area>.yamlwith apaths:map (and acomponents:map if it has its own components), in the same shape as the other area files. - Point
common.yamlat each of its paths, escaping/as~1in the pointer:/api/v2/organizations/{organizationId}/things: { $ref: './things.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1things' } - Add its tag and OAuth scopes to
common.yaml, then runbun run api:generate.