Overview
The engine's API for threads, majors and devices, and the accounts API
Everything the Mac and iPhone apps do goes through two HTTP APIs. This reference is generated from the same schemas the servers check requests with, so it matches what they accept.
| API | Address | What it covers |
|---|---|---|
| Engine | https://engine.keko.run | Threads, majors, approvals, changes, review, terminals, devices and Keko Cloud machines |
| Accounts | https://api.keko.run | Your account, sign-in, GitHub, AI accounts, usage and billing |
Each serves its own OpenAPI 3.1 document at /v1/openapi.json. The same documents are here too:
engine.json and accounts.json.
Authentication
Send Authorization: Bearer <token> with every request, and with every WebSocket upgrade, except the public ones such
as /v1/health. The engine takes a short-lived token from the accounts API: sign in with a device code through
https://api.keko.run/api/auth/device/code, then exchange the session for a token at https://api.keko.run/api/auth/token. Tokens last
15 minutes; ask for a new one when it expires.
Only Keko's own apps can sign in this way: the device-code endpoint takes the Mac app, the iPhone app and the
keko command, and refuses any other client. Other apps can't sign in to these APIs yet.
Following a thread
The engine's WebSocket routes stream changes as they happen: /v1/events for everything of yours, and
/v1/threads/{threadId}/watch for one thread. They're listed with the REST routes, marked as WebSocket, with what each side sends.
Requests that create things
Requests that start a thread or send a message take a requestId. Sending the same one again answers the first
request instead of sending twice, so a client can retry after a bad connection.
Errors
Errors come back with an HTTP status and a JSON body that says what went wrong in words:
{ "error": { "code": "unknown_request", "message": "Nothing waits for an answer on that call" } }