Skip to Content
Keko
API reference

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.

APIAddressWhat it covers
Enginehttps://engine.keko.runThreads, majors, approvals, changes, review, terminals, devices and Keko Cloud machines
Accountshttps://api.keko.runYour 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" } }

On this page