{ "openapi": "3.1.0", "info": { "title": "Descant API", "version": "1.0.0", "description": "The programmatic surface for a Descant tenant. This document is the CONTRACTED subset, not the whole product: the dashboard can do things no operation here covers yet, and the set grows as operations are specified. An absent capability means it is not contracted, never that it is forbidden." }, "servers": [ { "url": "https://app.descant.run" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "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 (`:`) the key must carry; a key without it is refused 403 before the operation runs." } } }, "paths": { "/api/v1/runs": { "get": { "operationId": "customer.runs.list", "summary": "List this key's tenant's runs, newest first.", "description": "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": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "Page size. Defaults to 50, clamped to 200; the applied value is echoed." } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." } }, { "name": "repositoryId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only this repository's runs. The id `customer.repos.list` returns, which is the only programmatic source of one. A repository belonging to another tenant matches nothing rather than erroring — the ownership join answers before the filter does." } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "idle", "picking", "planning", "implementing", "opening_pr", "under_review", "resolving", "merging", "capturing_learnings", "reviewing_learnings", "resolving_learnings", "merging_learnings", "filing_residuals", "grooming_issues", "refreshing_wiki", "verifying", "positioning_pr", "positioning_resolve", "self_reviewing", "fixing_ci", "decomposing", "done", "failed", "cancelled" ] }, "description": "Repeatable. The run's CURRENT state, not its outcome — `failed` and `cancelled` are terminal, `under_review` is not. Absent or empty means every state." } }, { "name": "createdAfter", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Runs created at or after this instant, INCLUSIVE. Filters the column the list orders by." } }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Runs created at or before this instant, INCLUSIVE. Filters the column the list orders by." } } ], "responses": { "200": { "description": "List this key's tenant's runs, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "issue": { "type": "string", "description": "The issue's external identifier, as the provider names it." }, "issueTitle": { "type": [ "string", "null" ], "description": "Snapshotted on the run (#3262). `null` on legacy runs and on seed paths that could not fetch it." }, "state": { "type": "string", "description": "The pipeline state. Open by design: states are added as the pipeline grows." }, "priority": { "type": [ "string", "null" ] }, "prNumber": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "provider": { "type": "string" }, "repoOwner": { "type": "string" }, "repoName": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dispatchBlockedReason": { "anyOf": [ { "type": "string", "enum": [ "slot", "vendor_budget" ] }, { "type": "null" } ], "description": "`slot`: the run's account is at its concurrency cap (#1995). `vendor_budget`: the fleet vendor budget, or this tenant's fair share of it, is exhausted (#7553), and only ever present when the operator has armed that budget. `null` on a run that is not parked." }, "dispatchWaiting": { "anyOf": [ { "type": "string", "enum": [ "paused-no-credits", "paused-cap", "waiting-for-slot", "waiting-for-vendor-budget" ] }, { "type": "null" } ], "description": "The dashboard's own reading of why this run rests. `null` when it is not waiting on any of these." } }, "required": [ "id", "issue", "issueTitle", "state", "priority", "prNumber", "provider", "repoOwner", "repoName", "startedAt", "finishedAt", "dispatchBlockedReason", "dispatchWaiting" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." }, { "type": "null" } ], "description": "`null` when this is the last page." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "description": "The page size actually applied, after clamping." }, "billing": { "anyOf": [ { "type": "object", "properties": { "pauseReason": { "anyOf": [ { "type": "string", "enum": [ "balance", "cap", "operator" ] }, { "type": "null" } ], "description": "The persisted pause reason, narrowed to the known set — an unrecognised future value reads as `null` rather than leaking." }, "outOfCredits": { "type": "boolean", "description": "Derived: the pause is a balance pause rather than an operator or cap pause. `false` with no billing signal." } }, "required": [ "pauseReason", "outOfCredits" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "items", "nextPageToken", "limit", "billing" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_query — A query parameter failed validation. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_query" ] } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/runs/{runId}": { "get": { "operationId": "customer.runs.get", "summary": "Read one run's timeline and findings, exactly as its own page shows them.", "description": "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": [ "runs:read" ] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read one run's timeline and findings, exactly as its own page shows them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "description": "The pipeline state. Open by design, as the list read's is." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "current", "failed", "held", "pending", "skipped", "stalled", "warning" ] }, "errorMessage": { "type": [ "string", "null" ], "description": "The MAPPED customer-facing copy, never the raw failure code — the projection strips that before it reaches any surface." }, "reviewIterations": { "type": "integer", "description": "How many review passes actually RAN. Present on the review step whenever that count is at least one, so `1` is an ordinary reviewed run rather than an anomaly; absent when no pass ran, and absent on every other step. The count is not a raw tally of review states: the pre-review positioning step maps to the same phase and is not a pass, and a drift-reposition abort re-enters the review state without running the reviewer, so it is subtracted rather than counted." } }, "required": [ "key", "label", "status", "errorMessage" ], "additionalProperties": false }, "description": "The five canonical phases as `deriveTimeline` derives them — the SAME call the page makes." }, "stepDetails": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "enteredAtMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "exitedAtMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "retries": { "type": "integer" } }, "required": [ "label", "enteredAtMs", "exitedAtMs", "retries" ], "additionalProperties": false } }, "description": "Sub-steps keyed by step `key`, for the steps that have them." }, "findings": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "list" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The stable finding id (`review-comment:`)." }, "threadUrl": { "type": [ "string", "null" ], "description": "Deep link to the PR review thread, or `null` where the coordinates make one underivable." }, "resolution": { "type": "string", "enum": [ "fixed", "rebutted", "outOfScope", "resolving", "pending" ] }, "rationale": { "type": [ "string", "null" ], "description": "The classifier's recorded prose about this tenant's own PR. `null` on a not-yet-classified item. FREE TEXT — see this family's note on `findings`." } }, "required": [ "id", "threadUrl", "resolution", "rationale" ], "additionalProperties": false } } }, "required": [ "kind", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "clean" } }, "required": [ "kind" ], "additionalProperties": false, "description": "The review ran and found nothing." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "resolvedSummary" }, "rounds": { "type": "integer" } }, "required": [ "kind", "rounds" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "outOfDiff" }, "findingsCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "kind", "findingsCount" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reviewUnresolvable" }, "findingsCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "kind", "findingsCount" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unrecorded" }, "findingsCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "kind", "findingsCount" ], "additionalProperties": false, "description": "A review whose findings never landed — NOT the same as `clean`." } ] }, "serverNowMs": { "type": "integer", "description": "The server clock this response was built at. Anchor every age against THIS, not the caller's clock." }, "stallAnchorMs": { "type": "integer", "description": "When the current customer-VISIBLE phase was entered — what the stall clock measures from. A multi-state visible phase deliberately does not reset it." }, "stateEnteredAtMs": { "type": "integer", "description": "The INTERNAL state's entry, verbatim — not bumped on a resolve self-loop." }, "resolveProgressAtMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastHeartbeatAtMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "finishedAtMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "currentStepNotStarted": { "type": "boolean", "description": "The run is at a phase that has produced no heartbeat, so it renders `stalled` rather than `current`. Derived ONCE server-side so every pane reads the same answer." }, "isTerminal": { "type": "boolean" }, "awaitingManualMerge": { "type": "boolean", "description": "A done run whose deliberately-unmerged PR still awaits a human." }, "skippedStepNote": { "type": "string", "description": "The note a `skipped` Merge step renders." }, "mergeStepNote": { "type": [ "string", "null" ], "description": "Non-null only where the merge took the host-backstop path because the Checks permission was never granted." }, "heldStepNote": { "type": [ "string", "null" ], "description": "Non-null only where the timeline actually carries a `held` Merge step." }, "baseBranch": { "type": [ "string", "null" ] }, "runKind": { "type": "string" }, "seededFromRunId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "The run this one was seeded from, where it was." }, "deferredFollowUpCount": { "type": "integer" }, "discretionFollowUpCount": { "type": "integer" }, "secondOrderFollowUpCount": { "type": "integer" }, "diminishingReturnsFollowUpCount": { "type": "integer" }, "unresolvedFollowUpCount": { "type": "integer" }, "adjudicatedSetAsideCount": { "type": "integer" }, "deferredOutOfDiffCount": { "type": "integer" }, "unanchoredCount": { "type": "integer" }, "toolingProposalCount": { "type": "integer" }, "selfReviewExplainedCount": { "type": "integer" }, "selfReviewResidualCount": { "type": "integer" }, "selfReviewResidualsWithAttempts": { "type": "integer" } }, "required": [ "state", "steps", "stepDetails", "findings", "serverNowMs", "stallAnchorMs", "stateEnteredAtMs", "resolveProgressAtMs", "lastHeartbeatAtMs", "finishedAtMs", "currentStepNotStarted", "isTerminal", "awaitingManualMerge", "skippedStepNote", "mergeStepNote", "heldStepNote", "baseBranch", "runKind", "seededFromRunId", "deferredFollowUpCount", "discretionFollowUpCount", "secondOrderFollowUpCount", "diminishingReturnsFollowUpCount", "unresolvedFollowUpCount", "adjudicatedSetAsideCount", "deferredOutOfDiffCount", "unanchoredCount", "toolingProposalCount", "selfReviewExplainedCount", "selfReviewResidualCount", "selfReviewResidualsWithAttempts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/rate_limited" }, "code": { "type": "string", "const": "rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 429 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/runs/{runId}/cancel": { "post": { "operationId": "customer.runs.cancel", "summary": "Stop a run that should not be running.", "description": "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": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stop a run that should not be running.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "cancelled", "cancel_requested", "already_finished", "privately_dispatched" ], "description": "How the cancel ended. `cancelled` is stopped. `cancel_requested` is RECORDED BUT NOT YET STOPPED — re-read the run rather than calling again. `already_finished` means there was nothing to stop and never will be. `privately_dispatched` means the work left this estate and cannot be recalled from here." } }, "required": [ "outcome" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "upstream_auth" ] } } } } } }, "503": { "description": "upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "upstream_timeout", "upstream_unavailable" ] } } } } } }, "504": { "description": "outcome_unknown — The action may have taken effect; verify before retrying. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "outcome_unknown" ] } } } } } } } } }, "/api/v1/repos": { "get": { "operationId": "customer.repos.list", "summary": "List this key's tenant's repositories.", "description": "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" ] } ], "parameters": [], "responses": { "200": { "description": "List this key's tenant's repositories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The tenant-repo id. What every repo-scoped operation takes." }, "owner": { "type": "string", "description": "The account or organisation that owns the repository on its provider." }, "repo": { "type": "string", "description": "The repository name, without the owner." }, "onboardedStatus": { "type": "string", "description": "Where this repository is in onboarding, as the column stores it. `pending` until both installation ids are populated and the validation smoke test succeeds, then `active`; `disconnected` is the terminal state after self-serve offboarding. NOT a closed set — the column carries no constraint, so treat an unrecognised value as unknown rather than as an error." }, "paused": { "type": "boolean", "description": "Whether the customer has paused this repository. A paused repository is not dispatched." } }, "required": [ "id", "owner", "repo", "onboardedStatus", "paused" ], "additionalProperties": false } } }, "required": [ "repos" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}": { "patch": { "operationId": "customer.repos.update", "summary": "Change whether a repository is paused, and what it picks.", "description": "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": [ "repos:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paused": { "type": "boolean", "description": "Whether this repository is paused. A paused repository is not dispatched." }, "orderStrategy": { "type": "string", "enum": [ "oldest-first", "newest-first" ], "description": "The direction the picker walks a tier. Built from the same `@descant/types` constant the runtime narrows against, so the contract and the picker cannot disagree about the vocabulary." }, "maxConcurrentRunsThisRepo": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483647 }, { "type": "null" } ], "description": "This repository's concurrency sub-cap. `null` CLEARS it, which is a real write and not an absence — the account cap alone then governs. The effective cap is `min(account, repo)`, so a value ABOVE the account cap is INERT rather than rejected: it will not raise anything. The upper bound is the column's own storage range, not a product ceiling." }, "eligibilityLabel": { "type": "string", "minLength": 1, "description": "The label an issue must carry to be eligible in `labeled` mode. Stored trimmed. THE LABEL MUST ALREADY EXIST ON THE REPOSITORY: this write does not create it, and a label the repository lacks makes pickup find nothing, with no error. Refused: empty, a `P` priority label, a comma, `blocked` or `waiting`, or a spelling a label-mapping value already uses." }, "eligibilityMode": { "type": "string", "enum": [ "labeled", "all-issues" ], "description": "Which issues are candidates at all: `labeled` requires the eligibility label, `all-issues` considers every open issue. Switching to `all-issues` keeps the stored label, so switching back restores it." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Change whether a repository is paused, and what it picks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "onboardedStatus": { "type": "string" }, "paused": { "type": "boolean" } }, "required": [ "id", "owner", "repo", "onboardedStatus", "paused" ], "additionalProperties": false }, "changed": { "type": "boolean", "description": "Whether this request actually moved anything. FALSE is a success, not a refusal: re-sending the state a repository is already in is an accepted no-op, and the audit trail records the intent either way." } }, "required": [ "repo", "changed" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_body — The request body failed validation. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_body" ] } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}/settings-audit": { "get": { "operationId": "customer.repos.settings-audit", "summary": "Read one repository's recorded settings intents, newest first.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read one repository's recorded settings intents, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "actor": { "type": "string", "description": "Who recorded the intent, as an OPAQUE string. The write side owns this vocabulary and a reader must not branch on its prefix shape. System pauses appear here alongside operator ones — the scheduler's evidence-driven auto-pause appends its own row actored `service:scheduler-autopause` — and `actor` is what tells them apart." }, "action": { "type": "string", "description": "The intent recorded, as the write side names it." }, "changed": { "type": "boolean", "description": "Whether this intent was a REAL change rather than a no-op re-assertion of the state already held." }, "detail": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "The row's detail, crossing the wire VERBATIM. ALWAYS PRESENT: a pause or resume carries its field transition; a `detach` records `null`, and that explicit null IS the persisted state — never an absence, never collapsed or dropped. The values are unbounded on purpose: the contract does not own this shape." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor", "action", "changed", "detail", "createdAt" ], "additionalProperties": false } } }, "required": [ "entries" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}/poller-status": { "get": { "operationId": "customer.repos.poller-status", "summary": "Read why this repository is or is not being polled.", "description": "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": [ "repos:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read why this repository is or is not being polled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "never-polled" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "no-eligible-issues" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "page-self-filed-only" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false, "description": "The whole page was filed by earlier runs of the pipeline, so the scheduler stood down rather than start another run whose only output is one more follow-up. The one stop here that needs NO remedy before work resumes." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "not-onboarded" }, "onboardedStatus": { "type": "string" } }, "required": [ "kind", "onboardedStatus" ], "additionalProperties": false, "description": "Onboarding is not finished. `onboardedStatus` is the column's own value and is not a closed set." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "billing-paused" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "balance", "cap", "operator" ] }, { "type": "null" } ], "description": "`balance`, `cap` or `operator`. `null` means the reason was absent OR was a value this deployment does not recognise — the handler degrades an unknown reason to null rather than leaking it, so null is 'paused, reason not established', never 'not paused'." } }, "required": [ "kind", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "paused-manual" }, "lastPolledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "kind", "lastPolledAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "paused-auto" }, "consecutiveFailures": { "type": "integer", "minimum": 0 }, "lastErrorClass": { "anyOf": [ { "type": "string", "enum": [ "rate-limited", "auth", "other" ] }, { "type": "null" } ] }, "lastPolledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "kind", "consecutiveFailures", "lastErrorClass", "lastPolledAt" ], "additionalProperties": false, "description": "Paused by the scheduler on repeated failure, not by a person. The settings-audit trail records this row actored as the service." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "held-page-exhausted" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false, "description": "The walk refused EVERY candidate on its page — the repository is held, not merely unproductive this tick." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "held-walk-stopped" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false, "description": "The walk STOPPED on a held candidate. Held on the same terms as `held-page-exhausted`, reached by a walk that stopped rather than one that exhausted a page." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "pickup-not-wired" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false, "description": "The worker holds the placeholder ticket source, so it is not picking up. A WORKER-level stop rather than a repository-level one, and the tick never consulted the ticket source at all." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "seeded" }, "runId": { "type": [ "string", "null" ] }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "runId", "lastPolledAt", "outcomeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "seeded-waiting-slot" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false, "description": "A run was seeded and is resting behind a concurrency gate." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "invalid-order-query" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "lastPolledAt", "outcomeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "error" }, "errorClass": { "anyOf": [ { "type": "string", "enum": [ "rate-limited", "auth", "other" ] }, { "type": "null" } ] }, "retriable": { "type": "boolean" }, "consecutiveFailures": { "type": "integer", "minimum": 0 }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "errorClass", "retriable", "consecutiveFailures", "lastPolledAt", "outcomeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "skipped" }, "reason": { "type": "string" }, "lastPolledAt": { "type": "string", "format": "date-time" }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When this outcome was reached. On a HELD kind it carries held-since; on `pickup-not-wired`, stopped-since; on `page-self-filed-only`, stood-since. `null` when the outcome carries no such instant." } }, "required": [ "kind", "reason", "lastPolledAt", "outcomeAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unknown-outcome" }, "raw": { "type": [ "string", "null" ] }, "lastPolledAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "raw", "lastPolledAt" ], "additionalProperties": false, "description": "The stored outcome is not one this deployment classifies — a newer writer, or a value since retired. `raw` carries it verbatim so an operator can act on what a reader could not." } ] }, "lastPoll": { "type": "object", "properties": { "polledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "outcome": { "type": [ "string", "null" ], "description": "The RAW stored outcome, unclassified. `status` is the reading of it." }, "errorClass": { "type": [ "string", "null" ], "description": "The raw stored error class, unnarrowed — unlike `status.errorClass`." }, "seededRunId": { "type": [ "string", "null" ] }, "outcomeAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "consecutiveTicketSourceUnavailableCount": { "type": "integer", "minimum": 0 } }, "required": [ "polledAt", "outcome", "errorClass", "seededRunId", "outcomeAt", "consecutiveTicketSourceUnavailableCount" ], "additionalProperties": false, "description": "The last tick's stored fields, beneath the classification. Use `status` unless you need what was persisted." }, "repo": { "type": "object", "properties": { "onboardedStatus": { "type": "string" }, "paused": { "type": "boolean" } }, "required": [ "onboardedStatus", "paused" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "paused": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "balance", "cap", "operator" ] }, { "type": "null" } ], "description": "Why billing paused this tenant, from the closed set the handler narrows to. `null` is 'paused, reason not established' — absent or unrecognised — never 'not paused'." }, "degraded": { "type": "boolean", "description": "Whether the billing read itself was degraded — so `paused` and `reason` may be stale rather than wrong." } }, "required": [ "paused", "reason", "degraded" ], "additionalProperties": false } }, "required": [ "status", "lastPoll", "repo", "billing" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}/config": { "get": { "operationId": "customer.repos.config", "summary": "Read what this repository is configured to pick, and in what order.", "description": "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": [ "repos:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read what this repository is configured to pick, and in what order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "eligibilityLabel": { "type": "string", "description": "The label an issue must carry to be eligible in `labeled` mode. Not consulted in `all-issues` mode." }, "eligibilityMode": { "type": "string", "enum": [ "labeled", "all-issues" ], "description": "Which issues are candidates at all. `labeled` requires the eligibility label; `all-issues` considers every open issue, and is why the diagnostics read reports no label-bucketed counts in that mode." }, "excludeAssigned": { "type": "boolean", "description": "Whether assigned issues are excluded. NOT durable operator policy: this is an AUTO-MANAGED recovery knob the reconciler can flip and restore without any operator write, so `false` must not be read as 'someone chose this'." }, "orderStrategy": { "type": "string", "enum": [ "oldest-first", "newest-first" ], "description": "The direction the picker walks a tier: oldest issue first, or newest first." }, "orderQueries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The persisted walk, verbatim, or `null` meaning the mode's default walk. `null` is the common case and is not an error." }, "effectiveOrderQueries": { "type": "array", "items": { "type": "string" }, "description": "DERIVED, NOT STORED — what the picker actually walks: `orderQueries` when set, otherwise the mode-aware default (the P0-P3 tiers plus the unlabeled final tier). Never write this back as configuration; `orderQueries` is the field that is set." }, "autoMergeEnabled": { "type": "boolean", "description": "Whether a run's pull request is merged automatically once it is green." }, "commitPlanDocument": { "type": "boolean", "description": "Whether runs also commit the plan document into the repository." } }, "required": [ "eligibilityLabel", "eligibilityMode", "excludeAssigned", "orderStrategy", "orderQueries", "effectiveOrderQueries", "autoMergeEnabled", "commitPlanDocument" ], "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}/issues": { "get": { "operationId": "customer.repos.issues.list", "summary": "List a repository's open issues, as the enqueue picker sees them.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "responses": { "200": { "description": "List a repository's open issues, as the enqueue picker sees them.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": false } }, "required": [ "configured" ], "additionalProperties": false, "description": "This deployment holds no author-App credentials, or this repository's author installation never landed. NOT an error: enqueue still works with an issue number you supply." }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "issues": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "The issue number as the provider names it — what an enqueue takes." }, "title": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "The issue's labels, for a caller filtering on the eligibility label before it enqueues." }, "bodySnippet": { "type": "string", "description": "The opening of the issue body, enough to recognise it in a list. Never the whole body." } }, "required": [ "number", "title", "labels", "bodySnippet" ], "additionalProperties": false } } }, "required": [ "configured", "issues" ], "additionalProperties": false } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_auth" }, "code": { "type": "string", "const": "upstream_auth" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 502 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_rate_limited — An upstream service is rate limiting us; retry after the stated interval. / upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_rate_limited" }, "code": { "type": "string", "const": "upstream_rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_timeout" }, "code": { "type": "string", "const": "upstream_timeout" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } } } } }, "/api/v1/repos/{id}/labels": { "get": { "operationId": "customer.repos.labels.list", "summary": "List a repository's label names, as the eligibility-label setting reads them.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "responses": { "200": { "description": "List a repository's label names, as the eligibility-label setting reads them.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": false } }, "required": [ "configured" ], "additionalProperties": false, "description": "As the issue picker's arm: enumeration is unavailable on this deployment, and setting an eligibility label by name still works." }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "configured", "labels" ], "additionalProperties": false, "description": "The repository's label NAMES, which is what the eligibility-label setting stores and matches on." } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_auth" }, "code": { "type": "string", "const": "upstream_auth" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 502 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_rate_limited — An upstream service is rate limiting us; retry after the stated interval. / upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_rate_limited" }, "code": { "type": "string", "const": "upstream_rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_timeout" }, "code": { "type": "string", "const": "upstream_timeout" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } } } } }, "/api/v1/repos/{id}/poller-diagnostics": { "get": { "operationId": "customer.repos.poller-diagnostics", "summary": "Explain why this repository's issues would or would not be picked.", "description": "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": [ "repos:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Explain why this repository's issues would or would not be picked.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": false, "description": "This deployment has no author-App credentials, or this repository's author installation never completed. No counts exist, and none are fabricated." } }, "required": [ "configured" ], "additionalProperties": false }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "mode": { "type": "string", "const": "all-issues", "description": "The repository picks from ALL issues, so label-bucketed counts would not describe what it picks. No counts are reported, deliberately." } }, "required": [ "configured", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "mode": { "type": "string", "const": "labeled" }, "diagnostics": { "type": "object", "properties": { "eligibilityLabel": { "type": "string", "description": "The configured label an issue must carry to be eligible." }, "assignmentFilter": { "type": "string", "enum": [ "exclude-assigned", "bot-only" ], "description": "How the effective filter treats assignment. `exclude-assigned` is the steady state. `bot-only` is RECOVERY mode, and it is narrower than the name suggests: ONLY the bot's own stranded issues qualify, not issues with any assignee." }, "totalEligibleLabeled": { "type": "integer", "minimum": 0, "description": "Open issues carrying the eligibility label. Bounded by one page — see `truncated`." }, "wouldQualify": { "type": "integer", "minimum": 0, "description": "Issues the tier walk would pick under the effective filter." }, "noPriorityLabel": { "type": "integer", "minimum": 0, "description": "Pass the assignment filter but carry no active P0-P3 label. Under the DEFAULT walk they are served by the unlabeled final tier after every priority tier, so ranked last rather than excluded. When `customOrdering` is true this count does NOT describe what the picker does: the bucketing is computed against the default tier semantics either way, while the picker walks the repository's own queries — an issue counted here may match one of those rows, and one counted in `wouldQualify` may match none. Read `customOrdering` first, and treat every count as default-walk semantics when it is true." }, "staleRawTier": { "type": "integer", "minimum": 0, "description": "STRANDED until relabeled, and the one bucket that names its own remedy. These carry a reserved raw `P0`-`P3` spelling whose tier is mapped elsewhere, so they are excluded from the tier legs AND from the unlabeled tail. Always 0 under the identity taxonomy." }, "assignmentExcluded": { "type": "integer", "minimum": 0, "description": "Excluded by the assignment filter, whether or not they carry a tier label — assignment gates the tier legs and the unlabeled tail alike." }, "truncated": { "type": "boolean", "description": "TRUE means the page came back full, so every count above covers only the first page of issues by recency and NOT the repository. A truncated count presented as a total is the one way this read misleads." }, "customOrdering": { "type": "boolean", "description": "TRUE when the repository configures an explicit `order_queries` array. The picker then walks exactly those rows with no implicit unlabeled tail. It is a CONFIG-LEVEL FACT rather than a classification bucket — the counts above are computed against the default tier semantics regardless — so when this is true, read them as 'what the default walk would do', not as a prediction of this repository's picker." } }, "required": [ "eligibilityLabel", "assignmentFilter", "totalEligibleLabeled", "wouldQualify", "noPriorityLabel", "staleRawTier", "assignmentExcluded", "truncated", "customOrdering" ], "additionalProperties": false } }, "required": [ "configured", "mode", "diagnostics" ], "additionalProperties": false } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "upstream_auth" ] } } } } } }, "503": { "description": "upstream_rate_limited — An upstream service is rate limiting us; retry after the stated interval. / upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "upstream_rate_limited", "upstream_timeout", "upstream_unavailable" ] }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/audit": { "get": { "operationId": "customer.audit.list", "summary": "List this tenant's authenticated API calls, newest first.", "description": "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:` when one of this tenant's credentials called, `user:` 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": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "Page size. Defaults to 50, clamped to 200; the applied value is echoed." } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." } }, { "name": "principal", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]*:.+$", "description": "Narrow the page to one credential's calls." } } ], "responses": { "200": { "description": "List this tenant's authenticated API calls, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "principal": { "type": "string", "minLength": 1, "description": "Who made the call, as an OPAQUE string the write side owns; do not branch on its prefix shape. A live row reads `api-key:`, or `user:` for a signed-in person exercising the same capability from the console; a row whose subject has been erased reads a redaction marker instead." }, "operationId": { "type": [ "string", "null" ], "description": "The operation the route serves, or `null` for a route the contract has not declared yet." }, "method": { "type": "string", "description": "The HTTP method, upper case." }, "path": { "type": "string", "description": "The request path without its query string. A segment may be a resource id, never prose." }, "scope": { "type": "string", "description": "The scope the operation required, `:`." }, "status": { "type": "integer", "description": "The HTTP status answered." }, "outcome": { "type": "string", "enum": [ "ok", "refused", "failed" ], "description": "Derived from `status`: below 400 ok, 4xx refused, 5xx failed." }, "requestId": { "type": "string", "description": "The `X-Request-Id` the response carried." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "principal", "operationId", "method", "path", "scope", "status", "outcome", "requestId", "createdAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." }, { "type": "null" } ], "description": "`null` when this is the last page." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "description": "The page size actually applied, after clamping." } }, "required": [ "items", "nextPageToken", "limit" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_query — A query parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_query" }, "code": { "type": "string", "const": "invalid_query" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/mcp": { "post": { "operationId": "customer.mcp.call", "summary": "Speak MCP to this tenant's API.", "description": "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" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "A JSON-RPC 2.0 message, as the Model Context Protocol defines it. This document does not restate that protocol: use an MCP client, which speaks it. The TOOLS reachable through this endpoint are the other operations in this document, one tool each.", "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Speak MCP to this tenant's API.", "content": { "application/json": { "schema": { "description": "A JSON-RPC 2.0 message, as the Model Context Protocol defines it. This document does not restate that protocol: use an MCP client, which speaks it. The TOOLS reachable through this endpoint are the other operations in this document, one tool each.", "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/rate_limited" }, "code": { "type": "string", "const": "rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 429 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/meta/operations": { "get": { "operationId": "customer.meta.operations", "summary": "List the customer operation ids and the contract version this deployment serves.", "description": "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.", "parameters": [], "responses": { "200": { "description": "List the customer operation ids and the contract version this deployment serves.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contractVersion": { "type": "string", "description": "`CONTRACT_VERSION` of the deployed registry — the same value a binary built from it reports as `contract`." }, "openapiVersion": { "type": "string", "description": "The OpenAPI version the document is written to." }, "audiences": { "type": "array", "items": { "type": "string", "enum": [ "customer", "admin" ] }, "minItems": 1, "description": "WHICH AUDIENCES THIS LISTING COVERS, and therefore what a diff against it can conclude. This route answers `[\"customer\"]`; an operation of an audience NOT named here is absent because it was not listed, never because the deployment does not serve it. A client must restrict its own side of the comparison to these audiences, or every unlisted id reads as one the deployment lacks." }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The operation id, exactly as the OpenAPI document and the CLI's `version --spec` spell it." }, "method": { "type": "string", "description": "The HTTP method, lowercase." }, "path": { "type": "string", "description": "The route template, with `{param}` placeholders." } }, "required": [ "id", "method", "path" ], "additionalProperties": false }, "description": "Every operation of the covered audiences that the deployed registry serves, in published order. A client diffs its own bundled registry — restricted to `audiences` — against this list; an id here and not there is one it cannot reach." } }, "required": [ "contractVersion", "openapiVersion", "audiences", "operations" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/auth/device": { "post": { "operationId": "customer.auth.device.start", "summary": "Begin a browser login and get the code the person will approve.", "description": "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.", "parameters": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "What to call this client on the approval page. Display only, and shown as untrusted text." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Begin a browser login and get the code the person will approve.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "description": "The secret half of the handshake: what the poll presents. Shown to nobody, stored only as a hash, and worth nothing once the key has been delivered against it." }, "userCode": { "type": "string", "description": "The short code a person reads and confirms, as `XXXX-XXXX`. Matched case-insensitively with the dash optional." }, "verificationUrl": { "type": "string", "format": "uri", "description": "Where the person approves. Carries the user code already filled in, so the common path is a click rather than typing." }, "expiresIn": { "type": "integer", "exclusiveMinimum": 0, "description": "Seconds until this authorization stops being redeemable." }, "interval": { "type": "integer", "exclusiveMinimum": 0, "description": "Seconds the client should wait between polls. Polling faster answers `slow_down`." } }, "required": [ "deviceCode", "userCode", "verificationUrl", "expiresIn", "interval" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/auth/device/token": { "post": { "operationId": "customer.auth.device.token", "summary": "Poll a browser login, and collect the key once it is approved.", "description": "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.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Poll a browser login, and collect the key once it is approved.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "pending" }, "interval": { "type": "integer", "exclusiveMinimum": 0, "description": "Seconds to wait before the next poll." } }, "required": [ "status", "interval" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "slow_down" }, "interval": { "type": "integer", "exclusiveMinimum": 0, "description": "The client polled faster than `interval`. Not a refusal: wait this long and poll again." } }, "required": [ "status", "interval" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "approved" }, "key": { "type": "string", "description": "The tenant API key (`dsc_…`), delivered once. A second poll answers `expired`." }, "keyId": { "type": "string", "format": "uuid", "description": "The key's id, so a person can find this key in the dashboard's list and revoke it." }, "tenantSlug": { "type": "string", "description": "Which organisation the person approved for. The CLI prints it so a two-tenant operator can see which one they got." }, "scopes": { "type": "array", "items": { "type": "string", "description": "`:`, from the closed set the contract publishes." }, "description": "What the approved key may exercise. Chosen by the person on the approval page, never by the client." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` never expires." } }, "required": [ "status", "key", "keyId", "tenantSlug", "scopes", "expiresAt" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "denied" } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "expired" } }, "required": [ "status" ], "additionalProperties": false } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/keys": { "get": { "operationId": "customer.keys.list", "summary": "List this tenant's API keys, newest first.", "description": "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": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "Page size. Defaults to 50, clamped to 200; the applied value is echoed." } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." } } ], "responses": { "200": { "description": "List this tenant's API keys, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "keyPrefix": { "type": "string", "description": "`dsc_` plus the first eight characters of the secret: how a key is named after it is minted." }, "scopes": { "type": "array", "items": { "type": "string", "description": "`:`, from the closed set the contract publishes." } }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` never expires." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` while the key is active." } }, "required": [ "id", "label", "keyPrefix", "scopes", "expiresAt", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } }, "nextPageToken": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512, "description": "Opaque, server-minted. Pass the previous response's `nextPageToken` verbatim; never construct one." }, { "type": "null" } ], "description": "`null` when this is the last page." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "description": "The page size actually applied, after clamping." } }, "required": [ "items", "nextPageToken", "limit" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_query — A query parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_query" }, "code": { "type": "string", "const": "invalid_query" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } }, "post": { "operationId": "customer.keys.create", "summary": "Mint a key holding a subset of this key's scopes.", "description": "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": [ "keys:write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 64 }, "scopes": { "type": "array", "items": { "type": "string", "description": "`:`, from the closed set the contract publishes." }, "minItems": 1, "description": "The scopes the new key holds. Must be a subset of the minting key's own — a key cannot widen itself." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the key stops authenticating. Omit for a key that does not expire. Must be in the future." } }, "required": [ "label", "scopes" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Mint a key holding a subset of this key's scopes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "keyPrefix": { "type": "string", "description": "`dsc_` plus the first eight characters of the secret: how a key is named after it is minted." }, "scopes": { "type": "array", "items": { "type": "string", "description": "`:`, from the closed set the contract publishes." } }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` never expires." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` while the key is active." }, "rawKey": { "type": "string", "description": "The secret, shown exactly once. It is stored hashed and cannot be recovered; a caller that loses it mints a new key." } }, "required": [ "id", "label", "keyPrefix", "scopes", "expiresAt", "createdAt", "lastUsedAt", "revokedAt", "rawKey" ], "additionalProperties": false } }, "required": [ "key" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "409": { "description": "conflict — The resource is not in a state that admits this.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/conflict" }, "code": { "type": "string", "const": "conflict" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/keys/{keyId}": { "delete": { "operationId": "customer.keys.revoke", "summary": "Revoke one of this tenant's keys.", "description": "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": [ "keys:write" ] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoke one of this tenant's keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "revoked", "already-revoked" ], "description": "`already-revoked` on a repeat: the key was not active, so nothing changed." } }, "required": [ "id", "outcome" ], "additionalProperties": false } }, "required": [ "key" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/keys/{keyId}/rotate": { "post": { "operationId": "customer.keys.rotate", "summary": "Replace a key with a successor; the old one lives on for a grace window.", "description": "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": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "graceSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 3600, "description": "How long the retired key keeps authenticating once the successor exists, in seconds. `0` retires it at once; the default is one hour; at most one day." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the SUCCESSOR stops authenticating. Omit for a successor that does not expire; the target's own expiry is not inherited. Must be in the future." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Replace a key with a successor; the old one lives on for a grace window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "keyPrefix": { "type": "string", "description": "`dsc_` plus the first eight characters of the secret: how a key is named after it is minted." }, "scopes": { "type": "array", "items": { "type": "string", "description": "`:`, from the closed set the contract publishes." } }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` never expires." }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` while the key is active." }, "rawKey": { "type": "string", "description": "The secret, shown exactly once. It is stored hashed and cannot be recovered; a caller that loses it mints a new key." } }, "required": [ "id", "label", "keyPrefix", "scopes", "expiresAt", "createdAt", "lastUsedAt", "revokedAt", "rawKey" ], "additionalProperties": false }, "retired": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the retired key stops authenticating: the earlier of its own expiry and the end of the grace window." } }, "required": [ "id", "expiresAt" ], "additionalProperties": false } }, "required": [ "key", "retired" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation. / invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "409": { "description": "conflict — The resource is not in a state that admits this.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/conflict" }, "code": { "type": "string", "const": "conflict" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/invites": { "get": { "operationId": "customer.invites.list", "summary": "List the key's own account's invites, with the budget and referral status.", "description": "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": [ "invites:read" ] } ], "parameters": [], "responses": { "200": { "description": "List the key's own account's invites, with the budget and referral status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The invite's id — what `customer.invites.revoke` takes." }, "status": { "type": "string", "description": "Open by design, as the run state is: statuses are added as the invite lifecycle grows." }, "createdAt": { "type": "string", "format": "date-time" }, "redeemedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "`null` while the invite is unredeemed." } }, "required": [ "id", "status", "createdAt", "redeemedAt" ], "additionalProperties": false }, "description": "METADATA ONLY — never the code or its hash. A list is re-readable, and a secret that can be re-read is not reveal-once." }, "budget": { "anyOf": [ { "type": "object", "properties": { "unlimited": { "type": "boolean", "const": true }, "remaining": { "type": "null" } }, "required": [ "unlimited", "remaining" ], "additionalProperties": false, "description": "No ceiling, so there is no count — `null` rather than a very large number a caller could do arithmetic on." }, { "type": "object", "properties": { "unlimited": { "type": "boolean", "const": false }, "remaining": { "type": "integer", "minimum": 0 } }, "required": [ "unlimited", "remaining" ], "additionalProperties": false, "description": "A ceiling, and what is left under it." } ] }, "referralStatus": { "type": "object", "properties": { "invitesConverted": { "type": "integer" }, "creditsEarnedMicros": { "type": "string", "description": "Micros as a decimal STRING, not a number: the value is exact and JSON numbers are not, which is the convention this API already uses for exact ids." } }, "required": [ "invitesConverted", "creditsEarnedMicros" ], "additionalProperties": false } }, "required": [ "invites", "budget", "referralStatus" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } }, "post": { "operationId": "customer.invites.create", "summary": "Mint one invite, and reveal its code once.", "description": "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": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "201": { "description": "Mint one invite, and reveal its code once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "description": "THE CODE, and this is the ONLY response that carries it. Surface it, hand it over, and do not persist it — nothing can return it again." }, "path": { "type": "string", "description": "The redemption path the code belongs to." } }, "required": [ "id", "code", "path" ], "additionalProperties": false }, "budget": { "anyOf": [ { "type": "object", "properties": { "unlimited": { "type": "boolean", "const": true }, "remaining": { "type": "null" } }, "required": [ "unlimited", "remaining" ], "additionalProperties": false, "description": "No ceiling, so there is no count — `null` rather than a very large number a caller could do arithmetic on." }, { "type": "object", "properties": { "unlimited": { "type": "boolean", "const": false }, "remaining": { "type": "integer", "minimum": 0 } }, "required": [ "unlimited", "remaining" ], "additionalProperties": false, "description": "A ceiling, and what is left under it." } ], "description": "The budget AFTER this mint, so a caller need not re-list to know what is left." } }, "required": [ "invite", "budget" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_body — The request body failed validation. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_body" ] } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "422": { "description": "invite_limit_reached — The tenant's invite limit is reached. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invite_limit_reached" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/invites/{id}": { "delete": { "operationId": "customer.invites.revoke", "summary": "Revoke one invite, reclaiming its budget slot.", "description": "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": [ "invites:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The invite id, as the list read returns it." } } ], "responses": { "200": { "description": "Revoke one invite, reclaiming its budget slot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true } }, "required": [ "revoked" ], "additionalProperties": false, "description": "A revoke that returns at all, succeeded. Every other outcome — no such invite, already terminal, somebody else's — is one indistinguishable `not_found`.", "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } } } }, "429": { "description": "rate_limited — Too many requests for this credential or source. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix. (legacy `{ error }` body)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "internal_error" ] } } } } } } } } }, "/api/v1/repos/{id}/grooming/candidates": { "get": { "operationId": "customer.repos.grooming.candidates", "summary": "Read the relationships Descant would propose for this repository's backlog.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "responses": { "200": { "description": "Read the relationships Descant would propose for this repository's backlog.", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The candidate's own id, derived from its content — what a caller cites when acting on it." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with", "together-with" ] }, "from": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "to": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string" }, "text": { "type": "string" } }, "required": [ "token", "text" ], "additionalProperties": false }, "description": "WHY the detector proposed this. `token` names the detector; `text` is the phrase from the tenant's own issue body that triggered it — free text, and the only free text this family publishes. It is the tenant's own backlog returned to that tenant, and without it a proposal is an assertion nobody can review." } }, "required": [ "id", "kind", "from", "to", "evidence" ], "additionalProperties": false }, "description": "PROPOSALS, not edges. Nothing exists until `dispatch` lands it." }, "asOf": { "type": "string", "description": "When this copy was last known to have no unprocessed backlog. A candidate is only as current as the copy it was derived from." }, "truncated": { "type": "boolean", "description": "The copy cut the backlog off, so the proposal set is over a partial view." }, "capped": { "type": "boolean", "description": "The detector stopped at its own ceiling, so there may be proposals it never reached." } }, "required": [ "candidates", "asOf", "truncated", "capped" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_unavailable — A service this operation depends on did not answer.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/repos/{id}/grooming/document": { "get": { "operationId": "customer.repos.grooming.document", "summary": "Read the relationship document this repository's issues currently encode.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "responses": { "200": { "description": "Read the relationship document this repository's issues currently encode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "The RESOLVED tier. See `priorityDisagreement` when the issue's two carriers disagree." }, "url": { "type": "string" }, "updatedAt": { "type": "string", "description": "THE CONFLICT TOKEN. Send it back in `dispatch`'s `expected` as `ref=updatedAt`; an issue that moved since you read it answers `conflict` rather than overwriting an edit you never saw." }, "order": { "anyOf": [ { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "`null` when the issue holds no rank." }, "ready": { "type": "boolean" }, "holds": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "enum": [ "graph", "tracker" ] }, "reason": { "type": "string" }, "label": { "type": "string", "enum": [ "claimed", "assigned", "filtered" ], "description": "The runner's one-word chip for a hold it imposes. `tracker` holds only, and not all of them — a cut-short readiness verdict and a unit over its member cap carry none." } }, "required": [ "family", "reason" ], "additionalProperties": false } } }, "required": [ "rank", "ready", "holds" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` on a closed issue: it holds no position." }, "priorityDisagreement": { "anyOf": [ { "type": "object", "properties": { "usedLabel": { "type": "string", "description": "The tier label AS WRITTEN ON THE ISSUE, never the configured spelling." }, "ignoredPriority": { "type": "integer", "description": "The frontmatter tier that was set aside; the format resolves label-first." } }, "required": [ "usedLabel", "ignoredPriority" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when the issue's label and its frontmatter name different tiers. Recorded rather than derived — by the time `priority` exists the two have been collapsed into one number." }, "unit": { "type": "array", "items": { "type": "string" } }, "lead": { "type": [ "string", "null" ] }, "effectivePriority": { "anyOf": [ { "type": "number", "enum": [ 0, 1, 2, 3 ] }, { "type": "null" } ] }, "promotedBy": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title", "state", "updatedAt", "order", "priorityDisagreement", "unit", "lead", "effectivePriority", "promotedBy" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Derived from the edge's content rather than assigned, so the same relationship has the same id wherever it is read." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with", "together-with" ] }, "from": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "to": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." } }, "required": [ "id", "kind", "from", "to" ], "additionalProperties": false } } }, "required": [ "issues", "edges" ], "additionalProperties": false, "description": "The whole document — issues and edges together. Never a patch or a slice; see the family header." }, "asOf": { "type": "string", "description": "When this copy was last known to have no unprocessed backlog." }, "truncated": { "type": "boolean", "description": "The open enumeration was CUT at the row cap — surfaced rather than laundered into a shorter backlog." }, "cycleGraphIncomplete": { "type": [ "string", "null" ], "description": "Non-null when the cycle check could not see the whole graph, naming why — a caller must not read 'no cycles' from an incomplete one. A write that could close a cycle is refused while this is set." }, "encodingRefused": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "diagnostic": { "type": "string" } }, "required": [ "ref" ], "additionalProperties": false }, "description": "Issues whose relationships could not be encoded back into their bodies. Their edges are readable here and are NOT persisted upstream." }, "host": { "type": "object", "properties": { "concurrencyCap": { "type": "integer" }, "running": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The document key of the issue being worked — `owner/repo#N`." }, "phase": { "type": "string", "description": "The runner's phase word, in the operator's vocabulary." }, "startedAt": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "key", "phase", "startedAt", "title", "url" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "The open enumeration was cut, so the host's own counts are omitted rather than stated as totals." } }, "required": [ "running", "truncated" ], "additionalProperties": false, "description": "What the HOST is doing right now — the runs in flight and the cap over them. An object, not a name: an earlier cut declared this a string and the strict schema rejected every real answer." } }, "required": [ "document", "asOf", "truncated", "cycleGraphIncomplete", "encodingRefused", "host" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_unavailable — A service this operation depends on did not answer.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/repos/{id}/grooming/dispatch": { "post": { "operationId": "customer.repos.grooming.dispatch", "summary": "Land one relationship edit in the issue bodies, fenced on what the caller read.", "description": "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": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "create", "delete", "retype", "flip" ], "description": "WHICH edit. The fields that go with it are listed in this operation's description and checked by the route." }, "mutationId": { "type": "string", "minLength": 1, "description": "YOURS TO MINT, required on every op, and echoed in this deployment's logs so one edit can be traced end to end. It is NOT replay protection: nothing here deduplicates on it, and resending the same id performs the edit again. `expected` is what makes a replay safe — a stale stamp answers `conflict` rather than writing twice." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with" ], "description": "`create` only: the relationship to add. `together-with` is absent deliberately — the writer cannot splice it, so offering it would advertise a create that always fails." }, "from": { "type": "string", "minLength": 1, "description": "`create` only." }, "to": { "type": "string", "minLength": 1, "description": "`create` only." }, "edgeId": { "type": "string", "minLength": 1, "description": "`delete`, `retype` and `flip`: the relationship being changed, as the document returns it." }, "nextKind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with" ], "description": "`retype` only: what the relationship becomes. Not `together-with`, for the reason `kind` gives — and a retype OUT of an existing `together-with` is refused by the writer too, which no enum here can say." }, "expected": { "type": "array", "items": { "type": "string" }, "description": "THE CONFLICT FENCE, as `issueRef=updatedAt` entries — the stamps you hydrated with. An issue that moved upstream since then answers `conflict` with the authoritative document rather than overwriting an edit you never saw. Entries rather than a map because the flag generator has no spelling for a map; the route splits them on the first `=`." } }, "required": [ "op", "mutationId", "expected" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Land one relationship edit in the issue bodies, fenced on what the caller read.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "const": "applied" }, "document": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "The RESOLVED tier. See `priorityDisagreement` when the issue's two carriers disagree." }, "url": { "type": "string" }, "updatedAt": { "type": "string", "description": "THE CONFLICT TOKEN. Send it back in `dispatch`'s `expected` as `ref=updatedAt`; an issue that moved since you read it answers `conflict` rather than overwriting an edit you never saw." }, "order": { "anyOf": [ { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "`null` when the issue holds no rank." }, "ready": { "type": "boolean" }, "holds": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "enum": [ "graph", "tracker" ] }, "reason": { "type": "string" }, "label": { "type": "string", "enum": [ "claimed", "assigned", "filtered" ], "description": "The runner's one-word chip for a hold it imposes. `tracker` holds only, and not all of them — a cut-short readiness verdict and a unit over its member cap carry none." } }, "required": [ "family", "reason" ], "additionalProperties": false } } }, "required": [ "rank", "ready", "holds" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` on a closed issue: it holds no position." }, "priorityDisagreement": { "anyOf": [ { "type": "object", "properties": { "usedLabel": { "type": "string", "description": "The tier label AS WRITTEN ON THE ISSUE, never the configured spelling." }, "ignoredPriority": { "type": "integer", "description": "The frontmatter tier that was set aside; the format resolves label-first." } }, "required": [ "usedLabel", "ignoredPriority" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when the issue's label and its frontmatter name different tiers. Recorded rather than derived — by the time `priority` exists the two have been collapsed into one number." }, "unit": { "type": "array", "items": { "type": "string" } }, "lead": { "type": [ "string", "null" ] }, "effectivePriority": { "anyOf": [ { "type": "number", "enum": [ 0, 1, 2, 3 ] }, { "type": "null" } ] }, "promotedBy": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title", "state", "updatedAt", "order", "priorityDisagreement", "unit", "lead", "effectivePriority", "promotedBy" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Derived from the edge's content rather than assigned, so the same relationship has the same id wherever it is read." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with", "together-with" ] }, "from": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "to": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." } }, "required": [ "id", "kind", "from", "to" ], "additionalProperties": false } } }, "required": [ "issues", "edges" ], "additionalProperties": false, "description": "The whole document — issues and edges together. Never a patch or a slice; see the family header." }, "asOf": { "type": "string", "description": "When this copy was last known to have no unprocessed backlog." }, "truncated": { "type": "boolean", "description": "The open enumeration was CUT at the row cap — surfaced rather than laundered into a shorter backlog." }, "cycleGraphIncomplete": { "type": [ "string", "null" ], "description": "Non-null when the cycle check could not see the whole graph, naming why — a caller must not read 'no cycles' from an incomplete one. A write that could close a cycle is refused while this is set." }, "encodingRefused": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "diagnostic": { "type": "string" } }, "required": [ "ref" ], "additionalProperties": false }, "description": "Issues whose relationships could not be encoded back into their bodies. Their edges are readable here and are NOT persisted upstream." }, "host": { "type": "object", "properties": { "concurrencyCap": { "type": "integer" }, "running": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The document key of the issue being worked — `owner/repo#N`." }, "phase": { "type": "string", "description": "The runner's phase word, in the operator's vocabulary." }, "startedAt": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "key", "phase", "startedAt", "title", "url" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "The open enumeration was cut, so the host's own counts are omitted rather than stated as totals." } }, "required": [ "running", "truncated" ], "additionalProperties": false, "description": "What the HOST is doing right now — the runs in flight and the cap over them. An object, not a name: an earlier cut declared this a string and the strict schema rejected every real answer." } }, "required": [ "outcome", "document", "asOf", "truncated", "cycleGraphIncomplete", "encodingRefused", "host" ], "additionalProperties": false, "description": "The edit landed; `document` is the authoritative state afterwards, and its `updatedAt` tokens are the ones to fence your next edit on." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "unchanged" }, "document": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "The RESOLVED tier. See `priorityDisagreement` when the issue's two carriers disagree." }, "url": { "type": "string" }, "updatedAt": { "type": "string", "description": "THE CONFLICT TOKEN. Send it back in `dispatch`'s `expected` as `ref=updatedAt`; an issue that moved since you read it answers `conflict` rather than overwriting an edit you never saw." }, "order": { "anyOf": [ { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "`null` when the issue holds no rank." }, "ready": { "type": "boolean" }, "holds": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "enum": [ "graph", "tracker" ] }, "reason": { "type": "string" }, "label": { "type": "string", "enum": [ "claimed", "assigned", "filtered" ], "description": "The runner's one-word chip for a hold it imposes. `tracker` holds only, and not all of them — a cut-short readiness verdict and a unit over its member cap carry none." } }, "required": [ "family", "reason" ], "additionalProperties": false } } }, "required": [ "rank", "ready", "holds" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` on a closed issue: it holds no position." }, "priorityDisagreement": { "anyOf": [ { "type": "object", "properties": { "usedLabel": { "type": "string", "description": "The tier label AS WRITTEN ON THE ISSUE, never the configured spelling." }, "ignoredPriority": { "type": "integer", "description": "The frontmatter tier that was set aside; the format resolves label-first." } }, "required": [ "usedLabel", "ignoredPriority" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when the issue's label and its frontmatter name different tiers. Recorded rather than derived — by the time `priority` exists the two have been collapsed into one number." }, "unit": { "type": "array", "items": { "type": "string" } }, "lead": { "type": [ "string", "null" ] }, "effectivePriority": { "anyOf": [ { "type": "number", "enum": [ 0, 1, 2, 3 ] }, { "type": "null" } ] }, "promotedBy": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title", "state", "updatedAt", "order", "priorityDisagreement", "unit", "lead", "effectivePriority", "promotedBy" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Derived from the edge's content rather than assigned, so the same relationship has the same id wherever it is read." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with", "together-with" ] }, "from": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "to": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." } }, "required": [ "id", "kind", "from", "to" ], "additionalProperties": false } } }, "required": [ "issues", "edges" ], "additionalProperties": false, "description": "The whole document — issues and edges together. Never a patch or a slice; see the family header." }, "asOf": { "type": "string", "description": "When this copy was last known to have no unprocessed backlog." }, "truncated": { "type": "boolean", "description": "The open enumeration was CUT at the row cap — surfaced rather than laundered into a shorter backlog." }, "cycleGraphIncomplete": { "type": [ "string", "null" ], "description": "Non-null when the cycle check could not see the whole graph, naming why — a caller must not read 'no cycles' from an incomplete one. A write that could close a cycle is refused while this is set." }, "encodingRefused": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "diagnostic": { "type": "string" } }, "required": [ "ref" ], "additionalProperties": false }, "description": "Issues whose relationships could not be encoded back into their bodies. Their edges are readable here and are NOT persisted upstream." }, "host": { "type": "object", "properties": { "concurrencyCap": { "type": "integer" }, "running": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The document key of the issue being worked — `owner/repo#N`." }, "phase": { "type": "string", "description": "The runner's phase word, in the operator's vocabulary." }, "startedAt": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "key", "phase", "startedAt", "title", "url" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "The open enumeration was cut, so the host's own counts are omitted rather than stated as totals." } }, "required": [ "running", "truncated" ], "additionalProperties": false, "description": "What the HOST is doing right now — the runs in flight and the cap over them. An object, not a name: an earlier cut declared this a string and the strict schema rejected every real answer." } }, "required": [ "outcome", "document", "asOf", "truncated", "cycleGraphIncomplete", "encodingRefused", "host" ], "additionalProperties": false, "description": "The edit changed nothing — and it still carries the document, because 'nothing to do' is often said precisely BECAUSE your copy is stale: somebody else may have created the same edge already." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "rejected" }, "reason": { "type": "string" }, "landed": { "type": "boolean", "const": true, "description": "PRESENT ONLY WHEN THE WRITE ACTUALLY LANDED and the local copy does not yet hold it. DROP the document and the `updatedAt` tokens you are holding and re-read: the next edit judged on them would splice a stale body over the one just written. Absent on an ordinary refusal, where nothing changed." } }, "required": [ "outcome", "reason" ], "additionalProperties": false, "description": "The write was refused and nothing changed there — UNLESS `landed` is present, which reverses that: see the field. A rejection is an answer, not a transport failure, so it is a 200 and must not be retried as though the request never arrived." }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "conflict" }, "upstream": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "priority": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "The RESOLVED tier. See `priorityDisagreement` when the issue's two carriers disagree." }, "url": { "type": "string" }, "updatedAt": { "type": "string", "description": "THE CONFLICT TOKEN. Send it back in `dispatch`'s `expected` as `ref=updatedAt`; an issue that moved since you read it answers `conflict` rather than overwriting an edit you never saw." }, "order": { "anyOf": [ { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "`null` when the issue holds no rank." }, "ready": { "type": "boolean" }, "holds": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "enum": [ "graph", "tracker" ] }, "reason": { "type": "string" }, "label": { "type": "string", "enum": [ "claimed", "assigned", "filtered" ], "description": "The runner's one-word chip for a hold it imposes. `tracker` holds only, and not all of them — a cut-short readiness verdict and a unit over its member cap carry none." } }, "required": [ "family", "reason" ], "additionalProperties": false } } }, "required": [ "rank", "ready", "holds" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` on a closed issue: it holds no position." }, "priorityDisagreement": { "anyOf": [ { "type": "object", "properties": { "usedLabel": { "type": "string", "description": "The tier label AS WRITTEN ON THE ISSUE, never the configured spelling." }, "ignoredPriority": { "type": "integer", "description": "The frontmatter tier that was set aside; the format resolves label-first." } }, "required": [ "usedLabel", "ignoredPriority" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when the issue's label and its frontmatter name different tiers. Recorded rather than derived — by the time `priority` exists the two have been collapsed into one number." }, "unit": { "type": "array", "items": { "type": "string" } }, "lead": { "type": [ "string", "null" ] }, "effectivePriority": { "anyOf": [ { "type": "number", "enum": [ 0, 1, 2, 3 ] }, { "type": "null" } ] }, "promotedBy": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title", "state", "updatedAt", "order", "priorityDisagreement", "unit", "lead", "effectivePriority", "promotedBy" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Derived from the edge's content rather than assigned, so the same relationship has the same id wherever it is read." }, "kind": { "type": "string", "enum": [ "blocked-by", "decomposed-from", "duplicate-of", "serialize-with", "together-with" ] }, "from": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." }, "to": { "type": "string", "minLength": 1, "description": "An issue, as the store names it — OPAQUE by design: the store compares references and never parses, reformats or resolves one, and this deployment spells a home-repository reference differently from a cross-repository one. So the only shape promised here is non-empty. A well-formed reference the document does not hold is not a malformed request: it answers `rejected` naming the reference, because only the document can know." } }, "required": [ "id", "kind", "from", "to" ], "additionalProperties": false } } }, "required": [ "issues", "edges" ], "additionalProperties": false, "description": "The whole document — issues and edges together. Never a patch or a slice; see the family header." }, "asOf": { "type": "string", "description": "When this copy was last known to have no unprocessed backlog." }, "truncated": { "type": "boolean", "description": "The open enumeration was CUT at the row cap — surfaced rather than laundered into a shorter backlog." }, "cycleGraphIncomplete": { "type": [ "string", "null" ], "description": "Non-null when the cycle check could not see the whole graph, naming why — a caller must not read 'no cycles' from an incomplete one. A write that could close a cycle is refused while this is set." }, "encodingRefused": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "diagnostic": { "type": "string" } }, "required": [ "ref" ], "additionalProperties": false }, "description": "Issues whose relationships could not be encoded back into their bodies. Their edges are readable here and are NOT persisted upstream." }, "host": { "type": "object", "properties": { "concurrencyCap": { "type": "integer" }, "running": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The document key of the issue being worked — `owner/repo#N`." }, "phase": { "type": "string", "description": "The runner's phase word, in the operator's vocabulary." }, "startedAt": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "key", "phase", "startedAt", "title", "url" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "The open enumeration was cut, so the host's own counts are omitted rather than stated as totals." } }, "required": [ "running", "truncated" ], "additionalProperties": false, "description": "What the HOST is doing right now — the runs in flight and the cap over them. An object, not a name: an earlier cut declared this a string and the strict schema rejected every real answer." } }, "required": [ "outcome", "upstream", "asOf", "truncated", "cycleGraphIncomplete", "encodingRefused", "host" ], "additionalProperties": false, "description": "An issue moved upstream mid-edit. `upstream` is authoritative — re-derive against it and fence on ITS `updatedAt` tokens rather than resending." } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation. / invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_auth" }, "code": { "type": "string", "const": "upstream_auth" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 502 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } } } } }, "/api/v1/repos/{id}/order-preview": { "post": { "operationId": "customer.repos.order-preview", "summary": "Preview the whole ordering walk under an unsaved draft.", "description": "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": [ "repos:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "eligibilityMode": { "type": "string", "enum": [ "labeled", "all-issues" ], "description": "OMIT to keep the saved mode. `labeled` requires the eligibility label; `all-issues` considers every open issue. The same closed set `customer.repos.config` takes." }, "eligibilityLabel": { "type": "string", "description": "OMIT to keep the saved label. Validated against the stored label exactly as the save path validates it." }, "orderStrategy": { "type": "string", "enum": [ "oldest-first", "newest-first" ], "description": "OMIT to keep the saved strategy. The direction the picker walks a tier — the same closed set `customer.repos.config` takes." }, "excludeAssigned": { "type": "boolean", "description": "OMIT to keep the saved value. `false` MEANS false — no presence marker is needed here, because unlike an HTML checkbox a JSON key that is present is present." }, "labelMap": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The label map as `KEY=label` entries, split on the FIRST `=` so a label containing one survives. Keys: `P0`, `P1`, `P2`, `P3`, `type:bug`, `type:feature`, `type:chore`. OMIT to keep the saved map. Send `null` — or an empty array — to preview with NO mapping at all: `null` is the spelling that survives the generated CLI, where a repeatable flag given zero times is indistinguishable from omitting the field and so cannot express an empty list. An entry with an empty value (`P1=`) leaves THAT key unmapped, as the settings form reads a blank control. An unknown or repeated key is `invalid_body` naming the entry." }, "orderQueries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "THREE STATES, and the one field where absent and `null` differ. OMIT to keep the saved queries; send `null` to CLEAR them and preview with none; send an array to replace them. A caller that sends `null` meaning \"nothing to say about queries\" will preview a backlog with no queries at all." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Preview the whole ordering walk under an unsaved draft.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": false } }, "required": [ "configured" ], "additionalProperties": false, "description": "This deployment cannot reach the provider to walk the backlog. NOT an error: the ordering settings are still writable, the preview simply cannot be computed." }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "rows": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "description": "Where this issue lands in the walk, 1-based." }, "number": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "matchedRule": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "query" }, "index": { "type": "integer", "description": "Which `orderQueries` entry matched, 0-based — the row to edit if this attribution is wrong." }, "query": { "type": "string", "description": "The query text as the walk ran it." } }, "required": [ "kind", "index", "query" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tier" }, "index": { "type": "integer" }, "label": { "type": "string", "description": "The RESOLVED spelling the walk queried: the mapped label on a repository with a label map, the raw `P0`..`P3` otherwise." } }, "required": [ "kind", "index", "label" ], "additionalProperties": false, "description": "The default walk's priority tier." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unlabeled-tail" } }, "required": [ "kind" ], "additionalProperties": false, "description": "The default walk's final tier, which has no label and no index — the issues no earlier rule claimed." } ], "description": "Which rule put this issue where it is — the whole reason a preview is readable rather than just ordered." }, { "type": "null" } ], "description": "`null` when the issue is included by the walk's own fallback rather than by a rule." } }, "required": [ "position", "number", "title", "url", "labels", "createdAt", "matchedRule" ], "additionalProperties": false }, "description": "The walk, in order." }, "complete": { "type": "boolean", "description": "TRUE only when `rows` IS the whole backlog — which requires PROVING exhaustion, not merely finding no fault. False when `rows` reached `limit` (the walk stops there and drops the rest silently, so exhaustion is unprovable), or when any of `partial`, `searchIncomplete` or `tierTruncated` is set. Read THIS rather than assembling it, and treat `rows` as a prefix whenever it is false. A backlog of exactly `limit` reports false, which is the safe direction." }, "partial": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" }, "queryIndex": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "kind", "queryIndex" ], "additionalProperties": false }, { "type": "null" } ], "description": "WHY the walk stopped, when it stopped on a query — `queryIndex` attributes it to an `orderQueries` row. One of three shortfall signals; `complete` is the one to branch on." }, "searchIncomplete": { "type": "boolean", "description": "The provider's own search did not return everything it matched. A shortfall the walk did not choose, so it carries no index." }, "tierTruncated": { "type": "boolean", "description": "A priority tier was cut before it was exhausted, so issues below the cut are absent from `rows` even though earlier tiers look complete." }, "limit": { "type": "integer", "description": "The ceiling the walk stopped at." }, "orderStrategy": { "type": "string", "description": "The strategy actually used, after the overlay was applied — echo it rather than assuming your draft took effect." }, "mirroredAsOf": { "type": "string", "description": "Present when this ordering was derived from the deployment's local copy rather than a live walk, dating that copy. ABSENT means the provider was walked just now." }, "mirroredCopy": { "type": "string", "enum": [ "behind", "unconfirmed" ], "description": "Present only when the copy that answered was NOT current: `behind` means it is known to trail the provider, `unconfirmed` means its position could not be confirmed. Absent alongside `mirroredAsOf` means the copy was current." } }, "required": [ "configured", "rows", "complete", "partial", "searchIncomplete", "tierTruncated", "limit", "orderStrategy" ], "additionalProperties": false } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation. / invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "409": { "description": "conflict — The resource is not in a state that admits this.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/conflict" }, "code": { "type": "string", "const": "conflict" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 409 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_auth" }, "code": { "type": "string", "const": "upstream_auth" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 502 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer. / upstream_rate_limited — An upstream service is rate limiting us; retry after the stated interval.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_timeout" }, "code": { "type": "string", "const": "upstream_timeout" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_rate_limited" }, "code": { "type": "string", "const": "upstream_rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } } } } }, "/api/v1/repos/{id}/ordering-preview": { "post": { "operationId": "customer.repos.ordering-preview", "summary": "Preview what one ordering query matches.", "description": "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": [ "repos:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The `tenant_repos` row, as `customer.repos.list` returns it." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "The one search to preview, in the provider's own query syntax." } }, "required": [ "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Preview what one ordering query matches.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": false } }, "required": [ "configured" ], "additionalProperties": false, "description": "As the whole-walk preview's arm: the provider is unreachable from this deployment, and that is not an error." }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "totalCount": { "type": "integer", "description": "How many issues the query matches — the number the author is usually checking." }, "items": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "title": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } }, "required": [ "number", "title", "labels", "createdAt" ], "additionalProperties": false }, "description": "A SAMPLE, not the whole match set. `totalCount` is the count; this is what it looks like." }, "executedQuery": { "type": "string", "description": "The query as actually sent, after the product's own scoping was folded in. Compare it against what you wrote when a result surprises you." } }, "required": [ "configured", "totalCount", "items", "executedQuery" ], "additionalProperties": false } ], "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "400": { "description": "invalid_path — A path parameter failed validation. / invalid_body — The request body failed validation.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_path" }, "code": { "type": "string", "const": "invalid_path" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/invalid_body" }, "code": { "type": "string", "const": "invalid_body" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 400 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } }, "401": { "description": "unauthenticated — No valid API key was presented. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unauthenticated" ] } } } } } }, "403": { "description": "forbidden — The key is valid but its scopes do not include the one this operation requires (the `security` entry names it). Refused before the operation runs. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "forbidden" ] } } } } } }, "404": { "description": "not_found — No such resource for this caller.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/not_found" }, "code": { "type": "string", "const": "not_found" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 404 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "429": { "description": "rate_limited — The per-credential rate limit refused the request before it was authenticated. Carries `Retry-After`. Answered by the audience's gate before the operation runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } } } }, "500": { "description": "internal_error — The request failed for a reason the caller cannot fix.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/internal_error" }, "code": { "type": "string", "const": "internal_error" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 500 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "502": { "description": "upstream_auth — An upstream service rejected this deployment's credential.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_auth" }, "code": { "type": "string", "const": "upstream_auth" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 502 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } } } }, "503": { "description": "upstream_timeout — An upstream service did not answer in time. / upstream_unavailable — A service this operation depends on did not answer. / upstream_rate_limited — An upstream service is rate limiting us; retry after the stated interval.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_timeout" }, "code": { "type": "string", "const": "upstream_timeout" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_unavailable" }, "code": { "type": "string", "const": "upstream_unavailable" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "code", "title", "status" ], "properties": { "type": { "type": "string", "const": "https://descant.run/problems/upstream_rate_limited" }, "code": { "type": "string", "const": "upstream_rate_limited" }, "title": { "type": "string" }, "status": { "type": "integer", "const": 503 }, "detail": { "type": "string" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" } } } ] } } } } } } } } }