Sign Up Sign In

HTTP API reference

The request and response shapes for every endpoint are generated from the code, not written by hand here. This page is a map: it points you at the interactive reference, the generated clients, and the handful of conventions that hold across all endpoints — each with a link to the concept that owns it. When this page and the generated schema disagree, the schema is right.

Interactive reference

Three views onto the same OpenAPI schema. Read shapes here; try calls here.

  • OpenAPI schema — the raw machine-readable contract, and the input the clients below are generated from.
  • Swagger UI — browse every endpoint and send authenticated calls from the browser.
  • Redoc — the same reference in a three-pane reading layout, easier for skimming.

Generated clients

You do not have to hand-roll HTTP. Two clients are generated from the schema above and live in the repo:

Both are regenerated from a running dev server with the make targets: build-api-schema writes the OpenAPI document, then build-api-client and build-api-client-python regenerate the TypeScript and Python clients from it. Because they are generated, they always match the live endpoints — including Approvals and Watches. The runnable scripts under examples/ consume the Python client directly, so they double as usage snippets.

Conventions

These hold across every endpoint. Each is stated once here and explained in full on the concept page that owns it.

  • Base path /v1/. Every endpoint lives under a versioned prefix (for example POST /v1/schedules/) so the contract can evolve without breaking callers. See Surfaces & authentication.
  • Bearer API-key auth. Send Authorization: Bearer aigears_live_…; the key identifies the Team, so there is no team id in the path. See Teams & API keys.
  • Error envelope. Failures return a JSON body of {"error": "<code>", "message": "<human text>"} (plus any error-specific fields); branch on the stable error code, not the message. See Surfaces & authentication.
  • Idempotency. Retry a create safely by sending the same Idempotency-Key header; the original response is replayed instead of making a duplicate. See Idempotency.