API
The Waltz REST API: base URL, sign-in, responses and the main resources.
Last updated
The console, the CLI and the MCP server all use one REST API. Everything the console does, the API does.
Base URL and reference
| Base URL | https://api.waltz.run/v1 |
| Reference | https://api.waltz.run/docs |
| OpenAPI document | https://api.waltz.run/openapi.json |
The reference lists every route, who may call it, its request and response shapes and the error codes it can answer.
Authentication
Sign-in is passwordless: POST /v1/auth/email-link sends a link, and redeeming it returns an access token and a refresh token. Send the access token as Authorization: Bearer <token>, and renew it with POST /v1/auth/refresh. The console uses HttpOnly cookies instead.
Two other tokens exist, each for one job: a CLI token only uploads agent sessions (CLI), and an MCP token only reads through /v1/mcp (MCP server).
Orgs and roles
The org is the tenant, named by its id in the path: /v1/orgs/{org}/…. Your membership is read on every request. An org you don't belong to answers 404 orgNotFound, never 403; a role below the route's answers 403 orgRoleInsufficient.
Responses
Success bodies are {"message", "code": "success", "data"}; errors are {"message", "code"}. Branch on code, never on message. Every response carries X-Request-ID; send your own to correlate logs. A limit your plan sets answers 402 planLimitReached, saying what the plan allows.
Main resources
Under /v1/orgs/{org}:
| Resource | Paths |
|---|---|
| Members and invitations | members, invitations |
| Integrations and repos | integrations, integrations/{vendor}/install, repos |
| People and teams | people, people/import, teams |
| Identities | identities, identities/unmatched, identity-candidates |
| Brief subscriptions | briefs/subscriptions, briefs/subscriptions/{subscription}/run |
| Briefs and editions | briefs, briefs/{brief}/editions, briefs/{brief}/diff |
| Review | briefs/{brief}/annotations, decisions, memory |
| Onboarding | onboarding, onboarding/suggested-subscriptions |
For example, list the Briefs of an org:
curl -H "Authorization: Bearer $WALTZ_TOKEN" \
https://api.waltz.run/v1/orgs/$ORG/briefs