Docs · API

The RepoOps hosted API

Everything a program needs to call repoops.ai: bind a device to a team, mint licenses, push telemetry and brain snapshots, read a brain with a scoped token, and read public product data. The contract itself is machine-readable.

The OpenAPI spec

The full surface is published at /openapi.json (OpenAPI 3.1). Every operation has a unique operationId, a description, typed parameters, and response schemas, so it loads directly into an LLM function-calling setup or any OpenAPI client generator.

curl -s https://www.repoops.ai/openapi.json | jq '.paths | keys'

Authentication: three bearer tokens

Every credential travels as Authorization: Bearer <token>, never in a URL. Which one an operation takes is named in the spec.

• Device token. Binds one machine to one team. Minted by POST /api/connect/exchange from a one-time connect code shown in the dashboard; rotated in place by POST /api/connect/rotate. This is the credential the desktop app, the daemon, and headless sensors use for every ingest endpoint.
• CLI token. A JWT from the RFC 8628 device-authorization flow: POST /api/cli/device/code, approve in the browser, then poll POST /api/cli/device/token. Used by npx repoops.
• Read token. A scoped, revocable capability minted in the dashboard (My Brain, then Personal read tokens). It is the only credential GET /api/me/brain/context accepts, and it can only read. The copy-paste client lives in the Integration Kit.

Errors are JSON

Failures return a structured body, never an HTML error page. The canonical shape carries a stable machine token next to the human message:

{ "ok": false, "code": "unauthorized", "error": "sign in to continue" }

Branch on code (snake_case, stable); never parse error, whose wording can change. Older endpoints return the reduced { "error": "..." } form; the spec documents the exact shape per operation. One deliberate exception: POST /api/cli/device/token answers with RFC 8628 machine codes (authorization_pending, slow_down, expired_token, invalid_grant) in the error key, because that RFC says so. A nonexistent /api/* path answers a JSON 404 with a hint naming this spec.

Rate limits

Ingest endpoints are limited per team; the device-authorization endpoints per IP. A 429 carries a retry-after header. Honor it before retrying.

Markdown for agents

Every public page on this site serves a markdown rendition when the request prefers it (Accept: text/markdown), with Vary: Accept set. The site overview for agents is /llms.txt; the full page index with a summary per page is /llms-full.txt.

MCP

The desktop app ships stdio MCP servers (repoops-brain, repoops-causal) that expose the local brain and the causal trail to any MCP-capable agent. They run on your machine against your data; see the MCP security model for the trust boundaries.

What is deliberately not here

Session-cookie dashboard routes, cron and webhook seams, and the enterprise SCIM/SSO endpoints (which follow their own RFCs) are not part of the public contract and are not in the spec. If an endpoint is not in /openapi.json, do not build against it.