REST API
The GitCafe REST API lives at https://git.cafe/api. Everything you can do in
the browser goes through it, and most of it is open to your own tools.
Find the endpoints
The API reference lists every operation with its parameters and response schemas. It is generated from the API itself, so it always matches the server you are using. The same description is available as OpenAPI 3.1 JSON for code generators, and as Markdown.
Authenticate
Send a credential as a bearer token:
| 1 | curl -H "Authorization: Bearer $GITCAFE_TOKEN" https://git.cafe/api/auth/principal |
- Personal access token: for scripts and CI. Create one in Settings → Tokens with only the permissions you need.
- OAuth: for applications acting for other users; see connect an API client.
- The CLI:
cafe api <path>sends an authenticated request using yourcafelogin, for examplecafe api "/repos/{owner}/{repo}"inside a clone.
Requests without a credential can read public data, with a lower rate limit.
Work with versions
Most resources carry a version number. When you change a resource, send the
version you read as expectedVersion. If someone changed it in the meantime,
the API answers 409 Conflict: read the resource again, check the new values,
and retry with the new version. This stops you from overwriting changes you
have not seen.
For PATCH edits to issues and pull requests, a stale version returns
409 with code: "VERSION_MISMATCH" and retryable: true. If current edit
authority is no longer available, it instead returns AUTHORIZATION_CHANGED
with retryable: false, even if the version is also stale. Check your access
before attempting another write. These diagnostics never expose the current
version without current authorization. Other conditional-write failures use
WRITE_REJECTED when the cause cannot be safely distinguished; do not assume
that every 409 is a version mismatch.
Retry safely
Operations that start work, such as merging, landing a stack, deleting a
branch or syncing a mirror, take a requestId that you choose (a UUID is a
good choice). If the response is lost, send the same request with the same
requestId again: you get the original result instead of a second operation.
Use a new requestId only when you mean to do something new.
Many such operations answer 202 Accepted with an operation you can poll.
Accepted means the work is queued, not finished; read the operation until it
reports a final state.
Page through lists
List responses return items and a next cursor. Pass next as the after
parameter to get the following page, and stop when next is null.
cafe api --paginate follows the cursors for you.
Explore public repositories
Public repository exploration (/api/explore/repos) requires at least one of
owner or topic. For example,
use /api/explore/repos?owner=gitcafe or /api/explore/repos?topic=rust.
Supplying both filters returns their intersection. Supplying neither returns
400, even with limit or after; those parameters only control pagination.
Neither filter is individually required, but the pair cannot both be absent.
Exploration always uses anonymous authority and never includes private repositories,
even when you send credentials.
Errors
Errors use application/problem+json with a type, title, status and
detail, and often a machine-readable code. A private repository you cannot
see answers 404, the same as one that does not exist. A request that does not
match the contract answers 400 validation-error, whose detail names up to
eight failing fields by path, such as query.state or body.labels.0, but
never their values.