API reference

Send the credential as a bearer token: Authorization: Bearer …. The schemes this API accepts:

• apiKey — A tenant API key, created in the dashboard and shown once. The tenant is taken from the key, never from the request. Each operation's `security` entry names the scope (`<family>:<read|write>`) the key must carry; a key without it is refused 403 before the operation runs.

Operation customer.runs.list. List this key's tenant's runs, newest first.

Read-only. The key's tenant is taken from the matched key row and never from the request, so a key cannot read another tenant's runs. Rate limited per source before authentication, so an unauthenticated caller cannot probe cheaply. Ownership-scoped (#3307): runs of a repository the tenant has since removed are still returned, because `customer.repos.list` still shows that repository and eliding its runs would lose audit history. Paged by an opaque page token — a run history is unbounded, and this list ALREADY stopped at fifty rows, silently, with no way to ask for the fifty-first; follow `nextPageToken` until it is `null`. The rows arrive as `items`, not `runs`: the array was never going to stay complete, and a renamed field is a break a caller can see rather than a truncation it cannot. `billing` is a tenant fact read once per request and rides every page unchanged. `repositoryId`, `state` and the `createdAfter`/`createdBefore` window each narrow the page and are each optional; absent means unfiltered. `invalid_query` covers a malformed page token — one this server did not mint, or one minted by another paged read — which is refused rather than read as `start over`.

Security: apiKey

Parameters

Response

Errors

Operation customer.runs.get. Read one run's timeline and findings, exactly as its own page shows them.

The run page's live snapshot under the key's own tenant: the five canonical phases as `deriveTimeline` derives them, their statuses and mapped copy, the server clocks a stall is measured against, the review findings and the follow-up counts. IT PUBLISHES WHAT THE PAGE RENDERS, through the same projection — so the two cannot tell a customer different stories about one run, and a test pins that they call the same function. The MAPPED failure copy crosses and the raw failure code does not; the derived findings view crosses and the raw review checkpoint does not. Measure every age against `serverNowMs` rather than the caller's clock. A missing run and another tenant's run are one indistinguishable `not_found`, so this is not an oracle for what somebody else owns.

Security: apiKey

Parameters

Response

Errors

Operation customer.runs.cancel. Stop a run that should not be running.

The write that stops spend. Answers WHICH ending it reached rather than a boolean: `cancel_requested` is recorded-but-not-yet-stopped and calls for a re-read, while `already_finished` is final and calling again will never change it. Refusals keep their own discriminant, and an `outcome_unknown` answer means the cancel MAY have landed: verify the run before calling again. A deployment that is not wired to the runner answers `internal_error`, which is an operator problem and not something a caller can fix by retrying.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.list. List this key's tenant's repositories.

Read-only, and the entry point for every repo-scoped operation: the `id` each of those takes is obtainable nowhere else on the programmatic surface. The key's tenant is taken from the matched key row and never from the request, so a key cannot list another tenant's repositories. Rate limited per source BEFORE authentication, so an unauthenticated caller cannot probe cheaply. Unpaginated — the whole list comes back.

Security: apiKey

Response

Errors

Operation customer.repos.update. Change whether a repository is paused, and what it picks.

A PARTIAL update: send only the fields you mean to change. An empty object is an accepted no-op answering `changed: false`, not a refusal — the published schema accepts it, so refusing it would make this contract disagree with the server about what is a valid body. An ABSENT field is left alone; a `null` `maxConcurrentRunsThisRepo` CLEARS the sub-cap, which is a real write rather than an absence. A sub-cap above the account cap is inert, not refused — the effective cap is the lower of the two. `changed: false` is a success: re-sending the current state is an accepted no-op. An eligibility label must already exist on the repository — this operation does not create it, and a missing label makes pickup find nothing without an error. A label spelled like a label-mapping value is refused. Read the stored pickup settings back with the repo config read; this response carries the repository's own fields only.

Security: apiKey

Parameters

Request body

Response

Errors

Operation customer.repos.settings-audit. Read one repository's recorded settings intents, newest first.

Who paused or resumed this repository, when, and whether the flip changed anything — readable by a key-holding program without a browser session. System pauses appear alongside operator ones, told apart by `actor`. A FIXED WINDOW of the 50 newest rows with no paging, so an empty `entries` is NOT proof the repository was never paused: it means nothing was recorded within that window. This is not a `paused` state oracle; the current pause reason is on the poller-status read. A malformed `id` answers `not_found`, exactly as an unknown or unreadable one does — never a validation error, so a caller cannot use the status to learn which ids are well-formed.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.poller-status. Read why this repository is or is not being polled.

The read that answers 'why is nothing happening'. `status` is a discriminated union over SIXTEEN causes, because 'not polling' has four different remedies and a boolean loses the difference: a repository HELD on its candidates, a worker that never consulted the ticket source, a billing pause, and a page already filed by earlier runs all look the same through `paused: true`. Branch on `status.kind`. `repo.paused` and `billing.paused` are the raw flags beneath that reading, and `lastPoll` is the stored tick beneath both. A malformed `id` answers `not_found`, exactly as an unknown or unreadable one does — never a validation error, so a caller cannot use the status to learn which ids are well-formed.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.config. Read what this repository is configured to pick, and in what order.

The rule behind the other two repo reads: which issues are candidates, which label makes one eligible, whether assigned issues are excluded, and the order the picker walks. Values are EFFECTIVE — the defaults are composed in when no row is stored, and no flag distinguishes the two, because they behave identically. `effectiveOrderQueries` is derived and must never be written back. A malformed `id` answers `not_found`, exactly as an unknown or unreadable one does.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.issues.list. List a repository's open issues, as the enqueue picker sees them.

The issues a run can be started for, read through this deployment's author App on the repository the path names — the same listing the console's picker renders. `configured: false` is a SUCCESS and means this deployment cannot enumerate (no author-App credentials, or this repository's author installation never landed); enqueue still works with an issue number you supply, so branch on the field rather than on the status. A malformed id, an unknown id and another tenant's id are one indistinguishable `not_found`, answered with no upstream call. Upstream failures are classified rather than proxied: `upstream_rate_limited` carries its interval and is worth retrying, `upstream_auth` is this deployment's credential and not yours to fix.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.labels.list. List a repository's label names, as the eligibility-label setting reads them.

The label NAMES this repository carries — what `customer.repos.update` stores as the eligibility label, and what the poller matches an issue against, so this is the read that makes that setting writable without guessing. `configured: false` is a SUCCESS on the same terms as the issue picker: setting a label by name still works when enumeration is unavailable. The `not_found` and upstream-classification rules are that operation's; see it.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.poller-diagnostics. Explain why this repository's issues would or would not be picked.

A LIVE read: one provider call per request, never cached. Answers what the picker would do right now — how many issues carry the eligibility label, how many would be picked, and which buckets hold the rest. TWO of the three success shapes report NO counts (`configured: false`, and `mode: "all-issues"`), because neither can be measured in label buckets and a fabricated zero would read as "nothing is eligible" rather than "not measured". Branch on `configured`, then on `mode`. Counts are bounded by one page: check `truncated` before reading any of them as a repository total, and by the DEFAULT tier semantics: when `customOrdering` is true the picker walks the repository's own queries and the buckets describe the default walk rather than what it would pick. A malformed `id` answers `not_found`, exactly as an unknown or unreadable one does.

Security: apiKey

Parameters

Response

Errors

Operation customer.audit.list. List this tenant's authenticated API calls, newest first.

One row per authenticated call against this tenant, including the ones that did not succeed: a 403 for a key outside its scope, and a 500 for a call that failed after it was admitted. A 429 is never here — the only one this surface answers is the pre-authentication per-source bound, which refuses before a credential is read and so has no tenant to attribute a row to. `principal` says who: `api-key:<keyId>` when one of this tenant's credentials called, `user:<userId>` when a signed-in person exercised the same capability from the console — a key minted on the settings page is the same capability as a mint over this API, and both leave a row. A call with no tenant to attribute is not recorded, so an empty page does not mean nothing was tried. Paged by an opaque page token; `principal` narrows to one caller. `invalid_query` covers a malformed page token — one this server did not mint, or one minted by another paged read — which is refused rather than read as `start over`.

Security: apiKey

Parameters

Response

Errors

Operation customer.mcp.call. Speak MCP to this tenant's API.

The Model Context Protocol endpoint. An agent connects an MCP client here and drives the operations in this document as typed tools, with this key's own credential. THE SCOPE THIS REQUIRES IS THE ENVELOPE, NOT THE CONTENTS: holding it means a key may open the transport, and every tool call inside is still checked against the scope its own operation requires — so a key with only read scopes can open this and still cannot write through it. Requests are stateless: each one is served independently and nothing is held between them.

Security: apiKey

Response

An empty object.

Errors

Operation customer.meta.operations. List the customer operation ids and the contract version this deployment serves.

Unauthenticated, and answered from the registry alone — no database, no credential, no tenant. What a client uses to learn whether it is behind: `descant version --check` diffs its bundled registry against this list and names the operations it cannot reach. IT COVERS THE CUSTOMER AUDIENCE ONLY, and says so in `audiences`. Those ids are what the OpenAPI document already publishes to anyone; the admin ids are not served here, because an unauthenticated caller is the person the help-listing ruling (#15338) protects and this would be the same disclosure on a wider channel. A caller holding an admin bearer is not that person and is served by its own operation. A client must restrict its own side of the diff to `audiences`, or every operation of an uncovered audience reads as one the deployment lacks. Carries no shapes or schemas — the OpenAPI document is the contract, this is its table of contents with a version stamp. Bounded by the per-source limiter every route under `/api/v1` pays.

Security: none

Response

Errors

Operation customer.auth.device.start. Begin a browser login and get the code the person will approve.

Unauthenticated, because it is what a caller with no credential uses to get one. Answers a secret `deviceCode` the client keeps, a short `userCode` a person reads, and the URL that shows the approval page. Nothing is minted here: the authorization sits pending until a signed-in person approves it, and it stops being redeemable after `expiresIn` seconds whether or not anyone does. Bounded by the per-IP limiter every route under `/api/v1` pays.

Security: none

Request body

Response

Errors

Operation customer.auth.device.token. Poll a browser login, and collect the key once it is approved.

Answers 200 with a `status` discriminant in every case a caller will meet: `pending` while nobody has decided, `slow_down` when the client polls faster than the `interval` it was given, `approved` carrying the key EXACTLY ONCE, `denied` when the person refused, and `expired` when the window closed. `expired` is also the answer for a `deviceCode` this server never minted and for one whose key has already been collected — deliberately one indistinguishable outcome, so a caller cannot use this endpoint to learn whether a code exists. Never 4xx for `pending`: a poll that has not been decided yet is the normal state of this operation, not an error.

Security: none

Request body

Response

Errors

Operation customer.keys.list. List this tenant's API keys, newest first.

Every key the tenant has minted, active and revoked, newest first — a revoke is a soft one, so a revoked key stays in this list with `revokedAt` set. Never the secret: only the display prefix. Paged by an opaque page token, because a key holding `keys:write` mints without a person and nothing bounds the row count; follow `nextPageToken` until it is `null`. `invalid_query` covers a malformed page token — one this server did not mint, or one minted by another paged read — which is refused rather than read as `start over`.

Security: apiKey

Parameters

Response

Errors

Operation customer.keys.create. Mint a key holding a subset of this key's scopes.

Mints a key for the same tenant, attributed to the same creating account as the minting key. The requested scopes must be a subset of the minting key's (a key cannot widen itself); `conflict` names the scope that is not held. A minting key with no creating account on record (a legacy key whose creator was erased) is refused with `conflict` rather than minting a child nothing is attributed to. The secret appears in this response and nowhere else.

Security: apiKey

Request body

Response

Errors

Operation customer.keys.revoke. Revoke one of this tenant's keys.

Soft-revokes: the row stays so the list can show it, and the key stops authenticating at once. A repeat reports `already-revoked`. A key id that belongs to another tenant, or to nothing, is one indistinguishable `not_found`. A key may revoke ITSELF; the call that does so is its last.

Security: apiKey

Parameters

Response

Errors

Operation customer.keys.rotate. Replace a key with a successor; the old one lives on for a grace window.

Mints a successor holding the target's label and scopes, attributed to the minting key's creating account, and sets the target to stop authenticating at the end of the grace window (`graceSeconds`: default one hour, `0` at once) or at its own expiry, whichever is earlier — an expiry is never extended. A rotation is a mint, so the minting key must hold every scope the target does; `conflict` names the scope that is not held. A target already revoked is `conflict` too: it has nothing to rotate. So is a target holding a scope the server answering does not recognise — rotating it would drop that scope from the successor permanently, so it is refused rather than silently narrowed; this can happen briefly while a deployment is rolling, and a retry clears it. A key may rotate itself. The successor's secret appears in this response and nowhere else.

Security: apiKey

Parameters

Request body

Response

Errors

Operation customer.invites.list. List the key's own account's invites, with the budget and referral status.

The invites belonging to the account that CREATED THIS KEY — not the tenant's current owner; see the family note, because which key you use decides whose budget you read. Metadata only: the invite code and its hash never appear here, only in the create response. A key with no creating account (minted before attribution, or one whose creator was erased) resolves to no account and answers `not_found`, the same answer as asking about somebody else's.

Security: apiKey

Response

Errors

Operation customer.invites.create. Mint one invite, and reveal its code once.

REVEAL-ONCE: the `code` and `path` exist in this response and nowhere else. Surface the link and do not persist the code — no read can return it, and a lost code means minting another. The body carries no fields, so an ABSENT or empty body is the natural call and is read as `{}`; a body with an unknown field is refused rather than ignored. Spending the account's last slot answers `invite_limit_reached` — a well-formed request that a rule refused, which is why it is not the malformed-body code. It spends the CREATING account's budget, which is the binding that keeps one co-owner's key from spending another's.

Security: apiKey

Response

Errors

Operation customer.invites.revoke. Revoke one invite, reclaiming its budget slot.

Kills the link and returns the slot to the account's budget — the same primitive the dashboard's per-row Revoke uses, so the two surfaces cannot drift. A missing invite, an already-terminal one and ANOTHER ACCOUNT'S are one indistinguishable `not_found`: the underlying predicate is on the acting account, so nothing here discloses that an invite exists for somebody else. That also means a revoke is safe to repeat in the sense that matters — the second call answers `not_found` rather than doing something new — but it is not idempotent in the `Idempotency-Key` sense and does not claim to be.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.grooming.candidates. Read the relationships Descant would propose for this repository's backlog.

PROPOSALS WITH THEIR EVIDENCE, not edges: nothing exists until `customer.repos.grooming.dispatch` lands it, and each candidate names the phrase in the tenant's own issue body that suggested it, because a relationship asserted with no reason cannot be reviewed. Served from the local copy of the backlog rather than a live walk — a proposal is a proposed WRITE against the copy the caller is looking at, so it must be derived from that same copy. `asOf`, `truncated` and `capped` say how current and how complete that copy was. WHEN THE COPY CANNOT SERVE, this answers `upstream_unavailable` and NEVER an empty list: an empty list is what a working detector returns over a backlog with no relationships, and the two must not be spelled the same.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.grooming.document. Read the relationship document this repository's issues currently encode.

The issues and the edges together, as the workspace renders them — what IS, where the candidates read is what COULD be. `cycleGraphIncomplete` is non-null when the cycle check could not see the whole graph: do not read 'no cycles' from an incomplete one. `encodingRefused` names issues whose relationships could not be written back into their bodies, so their edges are readable here and NOT persisted upstream — a distinction that decides whether another reader will see them. Mirror-served and typed-refusal on the same terms as the candidates read; see it.

Security: apiKey

Parameters

Response

Errors

Operation customer.repos.grooming.dispatch. Land one relationship edit in the issue bodies, fenced on what the caller read.

ONE mutation per call — create, delete, retype or flip — written into the GitHub ISSUE BODY through this repository's App installation. It does NOT seed a run and never reaches the runner, so no capacity answer applies. FENCED ON `expected`: issue ref to the `updatedAt` you hydrated with. An issue that moved since then answers `outcome: "conflict"` carrying the authoritative document, so a caller re-derives rather than overwriting an edit it never saw. WHEN AN ANSWER CARRIES A DOCUMENT IT IS THE WHOLE ONE, never a patch — `applied`, `unchanged` and `conflict` each carry it, and `unchanged` carries it precisely because 'nothing to do' is often said when your copy is stale and somebody else already created the edge. A `rejected` carries NO document: it carries a reason, and the `landed` flag if the write reached the issue before the failure. `rejected` means the write was refused upstream and nothing changed there — WITH ONE EXCEPTION that inverts it: a `rejected` carrying `landed: true` means the write DID land and only the local copy is behind, so drop the document and the `updatedAt` tokens you hold and re-read before your next edit. WHICH FIELDS GO WITH WHICH `op`, because the body is flat rather than a union: `create` takes `kind`, `from` and `to`; `delete` and `flip` take `edgeId`; `retype` takes `edgeId` and `nextKind`. `mutationId` is yours to mint and is required on every op. A field belonging to a different op is REFUSED rather than ignored — a body carrying both describes two edits and applying either is a guess — and a missing one answers `invalid_body` naming the field.

Security: apiKey

Parameters

Request body

Response

Errors

Operation customer.repos.order-preview. Preview the whole ordering walk under an unsaved draft.

What this repository's backlog WOULD be worked in, under a draft you have not saved — the point being to see the draft's effect before committing to it. THE BODY IS A PARTIAL OVERLAY and omission is meaningful: leaving a field out keeps the SAVED value, and `orderQueries` additionally distinguishes `null` (clear them) from absent (keep them). Sending `null` when you meant 'no opinion' previews a backlog with no queries. `partial` non-null means the walk did not finish and `rows` is a prefix rather than the answer. `configured: false` is a success meaning this deployment cannot reach the provider — the settings stay writable. It WRITES NOTHING: a preview computes and discards.

Security: apiKey

Parameters

Request body

Response

Errors

Operation customer.repos.ordering-preview. Preview what one ordering query matches.

The per-query half of the pair: what a single search actually matches, as a count plus a sample. An author checking a query they are writing wants this; an author checking the RESULT wants `customer.repos.order-preview`. `executedQuery` is the query as actually sent after the product's own scoping was folded in — read it when a result surprises you, because the difference is usually there. `items` is a sample and `totalCount` is the count; do not read the length of one as the other. It WRITES NOTHING.

Security: apiKey

Parameters

Request body

Response

Errors

What changed in the contract and why, newest first. An additive change keeps the version and is recorded under it; a breaking change is a new major and a new document.