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 (runs:read)

Parameters

Response

Errors

Operation customer.runs.start. Start a run on one issue.

Starts a run on one issue of a repository this key's account has connected, through the same checks the dashboard's start form makes, and answers the new run's id once it is queued. The run is started on behalf of the account that created the key. Every refusal says whether waiting can help. `capacity_exhausted` (the repository or account is at its concurrent-run limit) and `upstream_unavailable` mean nothing started and a later attempt may succeed, after `retryAfterSeconds` when the answer carries it. `billing_paused` clears when an owner resumes billing. `conflict` and `not_found` answer the same until something about the repository or the issue changes. A refusal the service named carries `reason`, from a closed set a caller can branch on: `repo-not-found`, `repo-paused`, `repo-not-active`, `repo-offboarding`, `repo-bench-fixture`, `fleet-halted`, `manual-merge-pending`, `run-active`, `serialize-held`, `slot-capped`, `together-unit-unsupported`, `together-unit-unresolvable`, `issuegraph-block-unreadable`, `issue-content-unavailable`, `terminal-failed-suppressed`, `terminal-failed-pr-open`, `held-pr-merged`, `terminal-failed-pr-merged`, `explained-done-pr-open`, `explained-done-pr-merged`, `deliverable-not-code`, `issue-closed` or `issue-decomposed`. A repository another account owns and one that does not exist are one indistinguishable `not_found`. A start over the API is treated as unattended: an issue whose latest run failed, or whose earlier pull request is still open or has already merged, is refused rather than run and billed again. A person can still start such an issue from the dashboard. `outcome_unknown` means the run may have started: read the runs list before starting again, because a second start is billed as a second run. Send an `Idempotency-Key` to make a retry safe: the same key and body within 24 hours answers the first result instead of starting a second run. When the service is known not to have started a run, the key is given back and a retry under it runs: always after `capacity_exhausted`, and after `upstream_unavailable` or `internal_error` when the run service answered. A key whose request may have started a run stays spent: every retry under it answers `outcome_unknown` until it expires, so read the runs list before starting again under a new key.

Security: apiKey (runs:write)

Parameters

Request body

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 cross as a field of its own; `endingClass` says whether the published list of expected endings names how the run ended, and `endingCause` names the cause for every ending. 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 (runs:read)

Parameters

Response

Errors

Operation customer.runs.activity. Read the steps one run took, as its activity page shows them.

The run's activity log under the key's own tenant: its attempts at each step, oldest first, with retries and earlier cycles after a restart included. IT PUBLISHES WHAT THE PAGE RENDERS, through the same read and 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. Each entry names its steps and its outcome in the page's own words. The mapped failure copy crosses on a failed attempt; the raw failure code does not. IT IS A BOUNDED TAIL, NOT THE WHOLE HISTORY: the run's most recent 500 attempts. Compare `attemptsRead` with `attemptsTotal` to tell a complete log from the tail of a longer one. Attempts earlier than the tail cannot be read through this operation, as they cannot on the page. 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 (runs:read)

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 (runs:write)

Parameters

Response

Errors

Operation customer.runs.restart. Restart a run that ended failed.

Re-enters the pipeline for a run that ended `failed` — the SAME run, so there is no new run id; re-read the run to watch it move. `awaitingSlot: true` means the restart is recorded and waits for a free run slot. `conflict` means the run or its repository is not in a state that admits a restart right now: the run is not `failed`, its repository is paused, another run is already working the issue, a restart is already in progress, the platform has paused new work, or the run's ending is one a restart cannot answer. It describes the state now and is not a promise that restarting can never succeed: re-read the run (`customer.runs.get`) and its repository (`customer.repos.list`), remedy what they show — resume a paused repository, for example — or wait for the competing run or the pause to clear, then restart again. A restart re-bills pipeline work, so the key's CREATOR must currently hold a role that may restart runs (today, an owner) in the key's organization: a key created by anyone else, or with no recorded creator, is refused with `forbidden`. An `outcome_unknown` answer means the restart MAY have landed: re-read the run before calling again.

Security: apiKey (runs:write)

Parameters

Response

Errors

Operation customer.runs.split-scorecard-get. Read a decomposing run's split scorecard, as its run page shows it.

What each leaf of the run's split went on to do, and what the split's outcomes say about where it was cut, under the key's own tenant. IT PUBLISHES WHAT THE RUN PAGE SHOWS, through the same read, so the two cannot tell a customer different stories about one split, and a test pins that they call the same function. Branch on `access`, then on `kind`. `absent` is a run that never decomposed; `unreadable` is one that did whose stored record cannot be read. Both are answers, not errors, and neither is the other. Every field of a scorecard is repository content, so a key whose creator may not read the run's repository gets `access: "summary"` and no scorecard. A leaf with no run reads `unobserved`, never as a zero, and a count after a restart is a floor; the fields say which. 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 (runs:read)

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 (repos:read)

Response

Errors

Operation customer.repos.connect. Connect a repository to this tenant.

The first step of onboarding, and the one every other repository operation needs: nothing else here can be called until a repository has an id, and an id exists only once it is connected. The tenant is the key's own — there is no tenant in the path, because a key resolves exactly one. Coverage is verified against the Apps themselves rather than read from a stored column. A repository the AUTHOR App cannot reach cannot be bound at all. A repository the REVIEW App cannot reach IS bound — the binding is real and will be picked up — and `awaiting` carries `review-app` so the caller knows nothing will stamp the review until that App is installed or widened. That is deliberate and matches what the console already does for the same customer: refusing here would make this API reject what the console accepts. A coverage lookup that did not COMPLETE is `upstream_unavailable` — nothing is known either way and the remedy is to retry, not to reinstall. `github_link_required` means the account that created the key has no usable GitHub link, never linked or needing to be reconnected, so nothing could be looked up: retrying is not expected to help until that account links or reconnects GitHub. Nothing was written, so it releases its Idempotency-Key, and once the link exists a retry under the same key runs again. A connected binding lands `pending`, NOT dispatching: read `awaiting` on the response for what is still owed. RE-CONNECTING A REPOSITORY THIS TENANT ALREADY HOLDS IS ACCEPTED, not refused: it answers 200 with `changed: false`. **That is not the same as nothing happening** — the bind rewrites the stored author App installation id on the existing row, and the review id when one is found, which repairs a binding whose ids had gone stale. It repairs THE IDS ONLY: a `suspended` or `revoked` binding is not cleared by re-connecting, and `customer.repos.activate` refuses it — read `onboardedStatus` to tell which case you are in. `changed: false` says you already HELD this repository; it does not say the call was inert, and it never means the binding was replaced. Branch on `changed`, NOT on an error — there is no `conflict` for this case and a caller that writes one has written dead code. That makes `connect` safe to retry, which matters for a call that creates a binding over a network that can drop the response. The OPERATOR path differs deliberately and refuses a repeat: an operator acting on someone else's tenant should be told the binding already exists, where a customer re-running their own setup should simply find it done.

Security: apiKey (repos:write)

Parameters

Request body

Response

Errors

Operation customer.repos.activate. Activate a connected repository.

FINISHES AN ONBOARDING — it does not simply make a repository active, and the difference is the boundary of this operation. It moves a `pending` binding to `active`. It does NOT reactivate a `suspended` or `revoked` one: that is a REPAIR, refused `conflict` here, and it lives on the operator path. Re-establishing what `active` asserts needs a live check of BOTH Apps' coverage, a refusal when the stored installation ids are gone, and a fence against the row moving underneath — none of which this operation performs, so a binding suspended BECAUSE its coverage was lost would otherwise be made schedulable by a call that never looked at coverage, and the scheduler would claim it every cadence and discard the work at seed with nothing raising an error. A `disconnected` or `detached` binding is also `conflict`; it needs re-onboarding. It writes ONE of the two columns the scheduler claims on and does NOT touch `paused` — a repository can be active and still idle, which is why `awaiting` is on every landed response and why a caller that reads only this operation's success can hold a repository that never dispatches. Clear `paused` with `customer.repos.update`. A repeat on a repository that is already active is a 200 answering `changed: false` and still reports the current state, exactly as the console's own control does when pressed on an active row. A repository this tenant does not hold is one indistinguishable 404, never a hint that it exists elsewhere.

Security: apiKey (repos:write)

Parameters

Response

Errors

Operation customer.repos.disconnect. Disconnect a connected repository, confirmed by its owner/name.

Ends this tenant's binding to a repository, the way the repository settings page's Disconnect does and through the same writer: polling stops, in-flight runs are force-failed and the repository's claims are released. `customer.repos.reconnect` takes it back. `confirmRepo` must echo the repository's `owner/name`; a mismatch is `conflict` too, and nothing changes. A repository this tenant does not hold and one outside what the key's creator may see are one indistinguishable `not_found`. One already disconnected or detached is `conflict`, as on `customer.repos.activate`: the binding is there, its status is readable on `GET /api/v1/repos/{id}`, and nothing is left to disconnect. The drain inside a disconnect is bounded, so a 200 can report `teardown: "draining"`: the repository is disconnected and some runs are still winding down. `outcome_unknown` is a disconnect that was sent and did not provably fail, so the repository may already be disconnected: read it with `GET /api/v1/repos/{id}` before anything else. To disconnect several repositories, call this once per repository, each with its own `owner/name`; the console's bulk disconnect does the same, one repository at a time through this writer.

Security: apiKey (repos:write)

Parameters

Request body

Response

Errors

Operation customer.repos.reconnect. Reconnect a disconnected repository.

Takes back a disconnect, the way the account page's Reconnect does and through the same steps: the repository is re-proved on GitHub for the key's creator exactly as `customer.repos.connect` proves a new one (both Apps' coverage, the owned-elsewhere and case-clash refusals, the member gate, review discovery), and then the binding moves from `disconnected` back to `pending`. It is NOT active yet: like a new connection it still owes validation, so read `awaiting` and finish with `customer.repos.validate` or `customer.repos.activate`. A repository this tenant does not hold and one outside what the key's creator may see are one indistinguishable `not_found`. `conflict` means the current state refuses a reconnect, and nothing changed: the repository is not disconnected (a repeat after a reconnect that landed answers this), an organization admin detached it, the account is closed, its runs are still winding down from the disconnect, or its name on GitHub changed since it was disconnected; read it with `GET /api/v1/repos/{id}`. `upstream_unavailable` is a coverage lookup that did not complete, so retry. `github_link_required` means the account that created the key has no usable GitHub link, so nothing could be looked up: retrying is not expected to help until that account links or reconnects GitHub, and the answer releases its Idempotency-Key. A 5xx answered before anything was written releases its Idempotency-Key, so a retry under the same key runs again. `outcome_unknown` is a reconnect that was sent and did not provably fail: read the repository before sending a new Idempotency-Key.

Security: apiKey (repos:write)

Parameters

Response

Errors

Operation customer.repos.validate. Prove a connected repository's install, and make it active.

Runs the repository's install validation, the onboarding validate page's check, through the same steps: both Descant Apps mint a token and must reach the repository, a verification issue is opened, commented on and closed in it, and the repository moves to `active`. Unlike `customer.repos.activate` it PROVES the install first, so it also returns a `suspended` or `revoked` repository to `active` once both Apps reach it again. It does not touch `paused`. A repository this tenant does not hold, one outside what the key's creator may see, and one already disconnected or detached are one indistinguishable `not_found`, and nothing is written for any of them. `conflict` means the install itself is not right — an App is not installed, or does not reach the repository, or the repository was suspended while the check ran — and `detail` names what to fix; nothing is activated, so fix the install and call again (under a new Idempotency-Key, if you sent one: a `conflict` is stored and replayed like any answer). `upstream_rate_limited` carries the interval to wait. `upstream_auth` and `internal_error` are this deployment's to fix, not yours. A 5xx answered before the verification issue was opened releases its Idempotency-Key, so a retry under the same key runs again; one answered after it does not, and a retry under that key answers `outcome_unknown` — read the repository with `GET /api/v1/repos/{id}` before sending a new key. A repeat on an active repository is a 200 with `transitionedToActive: false`, and opens and closes one more verification issue.

Security: apiKey (repos:write)

Parameters

Response

Errors

Operation customer.repos.get. Read one of this key's tenant's repositories by id.

The same fields `customer.repos.list` returns for this repository, read by its id, recorded onboarding facts included: reading them runs no validation and asks GitHub nothing. The key's tenant is taken from the matched key row and never from the request: an id this tenant does not hold answers `not_found`, exactly as a malformed or unknown one does. Read-only.

Security: apiKey (repos:read)

Parameters

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, and a `null` `docRoots` RESETS the documentation directories to the default — both real writes rather than absences. 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. Naming an eligibility label in `labeled` mode ALSO CREATES that label on the repository, best-effort and after the write itself has landed; if it could not be created the response still succeeds and carries `eligibilityLabelWarning`, whose ABSENCE means the label is there. In `all-issues` mode nothing is created, because the label gates nothing there. A write that names `eligibilityLabel`, `eligibilityMode` or `labelMap` also walks the stored ordering on the local copy, and if it now matches none of the issues the repository could pick up, the response still succeeds and carries `orderWalkWarning`. A label spelled like a label-mapping value is refused, and so is a label mapping spelled like the eligibility label. An eligibility or label-mapping change under which one of the stored ordering queries would match nothing is refused as `invalid_body`, as the settings page refuses it. A `labelMap` list REPLACES the stored label mapping and `null` or an empty list CLEARS it; the mapped labels are not created on the repository. The rest of what the settings page saves is here too: the base branch, auto-merge, whether assigned issues are skipped, whether a run may author workflow files, the area labels (`null` or an empty map CLEARS them) and the ordering queries (`null` restores the default walk). An ordering query or area map the settings page would refuse is refused as `invalid_body`, and a write naming `excludeAssigned`, `areaLabels` or `orderQueries` walks the ordering as an eligibility change does. The polling interval is not a repository setting a key can change. Read the stored settings back with the repo config read; this response carries the repository's own fields only.

Security: apiKey (repos:write)

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 (repos:read)

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 EIGHTEEN 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 (repos:read)

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. Also the documentation directories Descant keeps current, stored (`docRoots`) and effective (`effectiveDocRoots`, likewise derived), the stored label mapping (`labelMap`), and three settings the repo update writes that are not pickup policy: the base branch, the area labels and whether a run may author workflow files. A malformed `id` answers `not_found`, exactly as an unknown or unreadable one does.

Security: apiKey (repos:read)

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 (repos:read)

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 (repos:read)

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 how many issues carry the eligibility label, how many pass the label and assignment filters, which buckets hold the rest, and whether the last poll refused every candidate it examined. The buckets come before the walk checks each issue on its own terms, so a held repository can show counts and still start nothing: read `lastPollRefusals`. 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 (repos:read)

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 (audit:read)

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 (mcp:write)

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 (keys:read)

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. The secret appears in this response and nowhere else.

Security: apiKey (keys:write)

Parameters

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 retry carrying the same `Idempotency-Key` within 24 hours answers the first revoke instead. 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 (keys:write)

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 (keys:write)

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.

Security: apiKey (invites:read)

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 (invites:write)

Parameters

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: the second call answers `not_found` rather than doing something new. A retry carrying the same `Idempotency-Key` within 24 hours answers the first revoke instead.

Security: apiKey (invites:write)

Parameters

Response

Errors

Operation customer.invites.send. Mail one invite's link to an address.

Mails the link for one of the key's own account's still-pending invites to an address — the same send the dashboard's invite dialog makes, through the same service, so the two surfaces cannot drift. It takes the CODE, not the invite id: only the code's hash is stored, so the link cannot be rebuilt from an id, and a caller that no longer holds the code must revoke and mint another. `status: "sent"` means accepted for sending, never delivered: the mail goes out after the answer, best-effort, and it is the same answer for any well-formed address because nothing looks the address up. An address the service refuses is `invalid_body`, as is a malformed body. An unknown code, another account's, and one already redeemed or revoked are one indistinguishable `not_found`. Sends are metered per ACCOUNT on the same budget as the dashboard's send, charged before anything is checked, so a refused send spends it too; over it answers `rate_limited`. It acts on the account that CREATED the key, the binding every invite operation uses.

Security: apiKey (invites:write)

Parameters

Request body

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 (repos:read)

Parameters

Response

Errors

Operation customer.repos.grooming.next-candidates. Read the next proposals for this repository's backlog, past the ones you have answered.

THE SAME READ AS `customer.repos.grooming.candidates`, carrying the ids you have already answered. The proposal set is bounded, so a caller that only filtered its answers out of the plain read would get the same first page for ever. Here the answered ids are held back BEFORE the bound, and the page is proposals still to answer. IT IS A POST BECAUSE THOUSANDS OF IDS DO NOT FIT A URL, NOT BECAUSE ANYTHING CHANGES: it writes nothing, holds nothing between calls, and answers the same body over the same copy with the same page. `withheld` counts the current proposals your answers held back, and `nextPage` says whether a further read returns more. Served from the local copy and refused as `upstream_unavailable`, never an empty list, on the same terms as the plain read.

Security: apiKey (repos:read)

Parameters

Request body

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 (repos:read)

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 (repos:write)

Parameters

Request body

Response