The API reference lists every operation the SDK can call. A few public endpoints are not part of it, because they answer without a bearer token, authenticate with something else, or are called by a program that is not your code. They are all on https://api.overlane.app. A path not listed here is not a public contract.
Sign-in for the CLI
The CLI signs in with its own protocol. You normally never call these yourself; overlane auth login does. See Agent sign-in and agent tokens for what a person sees.
| Endpoint | What it does |
|---|---|
POST /auth/device |
Starts a device sign-in. Returns device_code, user_code, verification_uri, verification_uri_complete, expires_in and interval. |
POST /auth/device/token |
Polls with { "device_code": "..." }. Returns { access_token, token_type: "bearer", expires_in, tenantId } once a person has approved, or { error } with authorization_pending, slow_down, expired_token or access_denied. |
GET /auth/device/verify |
The page the person opens, with ?user_code=, to check the code and approve. |
POST /auth/repo/challenge |
Starts repository sign-in with { "repository": "owner/name", "code_challenge": "..." } (a base64url SHA-256 of a secret only the caller holds). Returns the challenge ID, the ref to push the proof commit to and its message. |
POST /auth/repo/token |
Finishes repository sign-in. Send either grant_type: "urn:overlane:grant-type:git-ref-proof" with challenge_id, code_verifier and optionally ref, or an RFC 8693 token exchange with a platform identity token as subject_token. Returns { access_token, token_type: "bearer", expires_in, tenantId, projectId }. |
Sign-in requests are rate limited per address and per repository. A refused request answers 429 with a Retry-After header.
The CI runner broker
A CI job gets one credential, bound to its team, run and job, that expires and cannot be used anywhere else. The runner uses it for four calls. They are not for your own code.
| Endpoint | What it does |
|---|---|
POST /v1/ci/broker/redeem |
Exchanges the credential for the secrets the job declared. Each secret redeems once. |
POST /v1/ci/broker/report |
Reports the job result when it ends. Sent with the credential as a bearer token. |
POST /v1/ci/broker/database/query |
Runs one SQL statement against the job’s own database. |
PUT /v1/ci/broker/artifacts/{name} |
Uploads a build artifact (up to 50 MB), with the team, run and job in x-overlane-tenant, x-overlane-run and x-overlane-job headers. |
A wrong or expired credential answers 401 with the code invalid_credential.
The release signing key
GET /v1/releases/public-key needs no token. It returns { algorithm: "Ed25519", publicKey, keyId }. The CLI and anything else that installs an Overlane release checks the release signature against this key. When the key is not set up, the answer is 503 with the code signing_unavailable.
The status page data
GET /status.json needs no token and allows any origin. It returns checkedAt, overall, a services list with the state of each public service and the recent incidents. It is cached for 30 seconds and never probes a service when you ask, so polling it is cheap.
The health check
GET /healthz (or HEAD) answers { "ok": true } when the API is up. It needs no token.
Inbound webhooks
These are addresses you give another service, so that it can call Overlane. None of them uses a bearer token. Each checks a signature over the raw body before it reads anything, and answers 401 with invalid_signature when the signature is wrong.
| Address | Sent by | How to set it up |
|---|---|---|
POST /webhooks/github |
The Overlane GitHub App | Set as the App’s webhook URL, with the content type JSON. The signature is X-Hub-Signature-256, an HMAC-SHA256 of the body with the App’s webhook secret. Issue and issue comment events feed issue sync, and the App’s install events connect repositories. |
POST /webhooks/bots/{botId} |
A bot you registered | Sign the body as in Bots: the Overlane-Signature header is t=<unix ms>, v1=<hex>, an HMAC-SHA256 of <t>.<body> with the bot’s signing secret. A timestamp more than five minutes off is refused. |
POST /webhooks/connectors/{team}/{provider} |
A connected service such as Slack, Linear or Sentry | The exact address and the secret to store are on each connector’s page. |
POST /webhooks/billing/stripe |
The payment provider | Set up by the operator of the service. Not for self-service use. |
POST /webhooks/billing/workos |
The identity and billing provider | Set up by the operator of the service. Not for self-service use. |
POST /webhooks/identity |
The identity provider | Set up by the operator of the service. Not for self-service use. |
For events Overlane sends to you, see Webhooks.