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.

Trying to connect an agent? Start with the Integration Kit for the copy-paste client, then use this page when you need the wire contract.

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.

Versioning and deprecation

This is API version 1, served at the unversioned paths documented in the spec. Pin it with a request header if you want a call to fail rather than drift:

RepoOps-Api-Version: 1

Omit the header and the current version answers, which is what every deployed client does today. Every response echoes the version that served it in the same header, and a pinned version this deployment does not serve answers 400 unsupported_api_version naming the ones it does. There is deliberately no /v1/ path prefix: the desktop app, the capture daemon, and the CLI are all deployed against these paths, and moving them would break every installed client for no benefit an agent can use.

What we promise about changes:

Additive changes ship without notice. A new endpoint, a new optional field, a new enum member. Your client must ignore fields it does not recognize.
Breaking changes never ship without notice. Removing or renaming an endpoint or a field, or narrowing a type. The affected endpoint carries an RFC 9745 Deprecation header and an RFC 8594 Sunset header for at least 180 days before the change lands, and it goes in the changelog.
A version keeps being served until its published sunset date passes.

Rate limits, in headers

Ingest endpoints are limited per team; the device-authorization and public-intake endpoints per IP. Rate-limited responses carry the RFC 9331 headers, so you can pace against the real budget instead of guessing:

RateLimit-Limit: 5
RateLimit-Remaining: 4
RateLimit-Reset: 42
RateLimit-Policy: minute;q=5;w=60, day;q=50;w=86400

RateLimit-Policy lists every quota an endpoint enforces; the discrete three describe whichever quota is nearest exhaustion, because that is the one that will stop you. A 429 adds Retry-After, never below one second. The endpoints an anonymous caller polls (/api/requests/status, /api/requests/ingest, and both device-authorization routes) send these on success too, so an agent can slow down before it is ever refused rather than after.

Markdown for agents

Most public pages on this site serve a markdown rendition when the request prefers it (Accept: text/markdown), with Vary: Accept set. Some routes are HTML only; they serve no markdown twin and send no Vary header. 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.