Rezee

API

One HTTP API behind everything - the web app, the rezee CLI, and whatever you build next. The reference is generated from the running server, so it is never out of date.

Open the interactive reference - every endpoint with its parameters and response, and a console that sends real requests once you paste a token.

Authenticating

Send a personal access token as a bearer token. Mint one under Settings → Tokens, or let rezee auth login mint a scoped one for you and keep it in your config.

$ curl -H "Authorization: Bearer reze_pat_..." \
    https://rezee.app/api/workspaces

A token can carry capabilities - issues:write, code:read, secrets:write - and a request outside them comes back 403 naming the capability it wanted. A token minted with no capabilities is unrestricted: it can do whatever its owner can. The browser's session cookie authenticates the same endpoints, which is what the web app uses.

Stability

Documented endpoints change additively. Fields get added; they are not removed, renamed, or retyped. New parameters are optional and new response fields are safe to ignore. Write clients that skip what they don't recognise and they will keep working.

There is no /v1 prefix. A version prefix promises a parallel old surface, and we would rather promise the thing we can keep: if a breaking change ever becomes necessary, it earns a prefix then, announced in the changelog - rather than arriving quietly under one that was there all along.

Endpoints under /internal are not part of this and are not published: they are the private channel between Rezee's own services.

Rate limits

Every /api request spends from a per-principal bucket - per token or account, not per address - except the liveness check and the event stream. It is set well above what a person or a CLI does and well below what a runaway loop does. Signing in and the device-login endpoints have their own, much stricter buckets.

Over the limit is 429 with a Retry-After header in seconds. Wait that long and try again; the allowance comes back on schedule whether or not you keep asking.

Conventions

  • JSON in, JSON out. Timestamps are ISO-8601 strings, ids are UUIDs.
  • Errors carry a plain-text message and the status that fits: 401 not signed in, 403 not allowed, 404 not there (or not yours to see), 409 already answered, 422 unprocessable. A 422 is the one that comes in two shapes: a message when the request was understood and refused, and a validation report - {type, on, property, message} - when a body failed its schema before the endpoint saw it.
  • Lists that page take page and perPage and answer with hasMore. Pipeline logs page by cursor instead: pass back the cursor you were given as after and you get only what has arrived since.
  • Git transport - clone, fetch, push - is not part of this API. It is plain git over HTTPS and SSH, with the same tokens and keys.

The CLI is built entirely on these endpoints, so anything it does you can do. If something it can do isn't in the reference, that's a bug worth telling us about.