API and authentication

The platform exposes versioned HTTP endpoints under /api/v1. Use your deployment's origin and a credential with only the permissions your integration needs. API availability and allowed operations still depend on the signed-in account, repository, and organization policy.

First request

The CLI can make an authenticated request without printing a token into a shell command:

gbb auth login
gbb api /api/v1/user

For a direct HTTP client, create a scoped personal access token in account settings and send it as a bearer credential over HTTPS. Do not put tokens in URLs, logs, or a public repository.

GET /api/v1/user HTTP/1.1
Authorization: Bearer <personal-access-token>

Contract and pagination

Check the deployed version before relying on an endpoint. The API endpoint reference lists the declared CLI integration contract, request fields, and response codes. It does not turn every internal route into a supported public interface.

Pagination is endpoint-specific. The contract declares page and per_page for repository issue, label, pull request, and Actions lists. For endpoints that return nextCursor, use gbb api --paginate to fetch more pages, up to the CLI's page limit. Do not assume the two schemes are interchangeable.

Treat authorization failures as a signal to review the token's scope and the resource permissions. Never retry a mutation blindly after a network timeout; first determine whether the request was applied.

Use the operation's documented Idempotency-Key or body request identity when provided. Keep the same identity for retries of the same logical request, and use a new identity for a different request. Webhooks explains event delivery; Troubleshooting covers common integration failures.