{ "openapi": "3.1.0", "info": { "title": "Assure API", "version": "262612b1426d", "description": "The Assure API at https://api.symbolia.ai. Merged from the four documents the Assure repository publishes at commit 262612b1426d4257b756b062480ad4fac59bd63a, each also served as written: /openapi/auth.json, /openapi/checks.json, /openapi/keys.json, /openapi/feedback.json. These documents cover sign-in, checks, keys and feedback. The other routes (lint, the free summary, the report, the proof tree, formalisation, usage, billing checkout, declaration proposals) are documented in the API quick start at /docs/quickstart-api.md, section 6." }, "servers": [ { "url": "https://api.symbolia.ai" } ], "paths": { "/v1/auth/oidc": { "post": { "operationId": "signInWithGitHubOidc", "description": "No Authorization header: the GitHub Actions OIDC token is the credential. The token is verified with RS256 against GitHub's published key set (issuer https://token.actions.githubusercontent.com), the whole PKCS#1 v1.5 block compared at once; alg must be RS256, kid must name a published key, aud must be assure (or a list holding it), exp, iat and nbf must hold within 60 s, and exp - iat must be at most 3600 s. The account is gh- followed by the repository_owner claim in lower case, created on the free plan the first time it signs in; a known account keeps its plan. The key expires at the token's exp or one hour from now, whichever comes first. No query parameters. Maximum body 16384 bytes, token 8192 bytes. Counts against the account's minute rate window.", "x-body-max-bytes": 16384, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInRequest" } } } }, "responses": { "200": { "description": "A key for this run; the answer also carries Assure-Key-Expires", "headers": { "Assure-Key-Expires": { "description": "The key's expires_at", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedIn" } } } }, "400": { "description": "bad_input: the body is not {\"token\": } or a query parameter was sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } }, "401": { "description": "unauthenticated: the token does not verify; detail.identity names the check that failed and detail.rule is oidc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } }, "405": { "description": "bad_input: method not allowed", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } }, "413": { "description": "oversize_input: body exceeds 16384 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } }, "429": { "description": "rate_limited: the account's minute window is full", "headers": { "Retry-After": { "description": "Seconds until another attempt may be made", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } }, "503": { "description": "server_busy: GitHub's signing keys cannot be read just now (detail.identity keys_unavailable)", "headers": { "Retry-After": { "description": "60", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure" } } } } } } }, "/v1/checks": { "post": { "operationId": "submitCheck", "description": "Submit collected files for one profile (QUICKSTART-API.md, section 4). 200 with the verdict when the check finishes within 20 seconds of the request (its upload and admission included; an admission past 19.5 seconds leaves the check half a second), else 202 with the check id to poll.", "responses": { "200": { "$ref": "#/components/responses/Verdict" }, "202": { "$ref": "#/components/responses/Running" }, "default": { "$ref": "#/components/responses/Failure" } } } }, "/v1/checks/{check_id}": { "get": { "operationId": "getCheck", "parameters": [ { "name": "check_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } ], "description": "The verdict of one of your checks, readable for 30 days; 202 while it runs.", "responses": { "200": { "$ref": "#/components/responses/Verdict" }, "202": { "$ref": "#/components/responses/Running" }, "default": { "$ref": "#/components/responses/Failure" } } } }, "/v1/profiles": { "get": { "operationId": "listProfiles", "description": "The served profiles, each with its input allow-list, byte caps and fail_on words, plus the global limits, the engine that answers, the planned profiles not served and the route table (QUICKSTART-API.md, section 6, the GET /v1/profiles row). Free.", "responses": { "200": { "description": "The profile listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileListing" } } } }, "default": { "$ref": "#/components/responses/Failure" } } } }, "/v1/keys/rotate": { "post": { "operationId": "rotateKey", "description": "The Authorization header's key is the credential and the subject. No body (Content-Length 0) and no query parameters. From the key's rotation window (Assure-Key-Expires minus 7 days, or the last quarter of its life) the answer is a new key for the same account and plan, expiring 30 days from now, with predecessor naming this key; inside the overlap a second rotate with the old key answers the same successor with reissued true. Before the window: 409 rotate_too_early, detail.opens_at the time it opens (null for a key with no expiry yet). Counts against the account's minute rate window.", "x-body-max-bytes": 0, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "The successor key; the answer also carries the presented key's Assure-Key-Expires", "headers": { "Assure-Key-Expires": { "description": "The presented key's expiry", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rotated" } } } }, "400": { "description": "bad_input: a body or a query parameter was sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_keys" } } } }, "401": { "description": "unauthenticated: the key is missing, malformed, unknown or revoked; key_expired: the key is past its expiry (detail.expires)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_keys" } } } }, "405": { "description": "bad_input: method not allowed", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_keys" } } } }, "409": { "description": "rotate_too_early: before the key's rotation window; detail.opens_at names when it opens and the key keeps working", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_keys" } } } }, "429": { "description": "rate_limited: the account's minute window is full", "headers": { "Retry-After": { "description": "Seconds until another attempt may be made", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_keys" } } } } } } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "description": "Free on every plan; no model call, charge, ledger row or verdict change. One UTF-8 JSON object, no duplicate keys, non-finite numbers or extra keys. No query parameters. One Content-Length header is required; Transfer-Encoding is refused. Maximum body 16384 bytes, text 4096 UTF-8 bytes. Shares the account minute rate window with checks. Maximum 100 new rows per account per UTC day. Daily deduplication is by account, kind, check_id and exact text; duplicate metadata does not replace the first row. A duplicate still uses the minute window. Notes are retained for 12 months, operator-enforced; removal on request is an operator act. consent_follow_up defaults false.", "x-body-max-bytes": 16384, "x-new-notes-per-account-utc-day": 100, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" }, "example": { "kind": "friction", "text": "The input instructions did not say which folder to pass. I expected an example folder layout.", "consent_follow_up": false } } } }, "responses": { "200": { "description": "Accepted or daily duplicate; text is not echoed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accepted" } } } }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/OversizeInput" }, "429": { "description": "rate_limited; detail.window is minute or day. Day waits until midnight UTC", "headers": { "Retry-After": { "description": "Seconds until another attempt may be made", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "500": { "$ref": "#/components/responses/CheckerError" } } } }, "/v1/feedback/{id}": { "get": { "operationId": "getFeedback", "description": "Reads only the authenticated account's row, including exact customer text. No query parameters. Malformed, absent and foreign-account ids all return the same not_found refusal. rows_unreadable counts unreadable lines in the id's UTC-day file, including zero. check_known is the own-account verdict lookup at original submission, not a live lookup.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^fb-[0-9]{8}-[0-9a-f]{16}$" } } ], "responses": { "200": { "description": "Stored own-account row", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stored" } } } }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "500": { "$ref": "#/components/responses/CheckerError" } } } } }, "components": { "schemas": { "Flags": { "type": "object", "required": [ "execution_authorized", "hardware_authorized", "industrial_release_authorized", "release_allowed", "physical_validation", "simulation", "self_approved" ], "properties": { "execution_authorized": { "type": "boolean", "const": false }, "hardware_authorized": { "type": "boolean", "const": false }, "industrial_release_authorized": { "type": "boolean", "const": false }, "release_allowed": { "type": "boolean", "const": false }, "physical_validation": { "type": "boolean", "const": false }, "simulation": { "type": "boolean", "const": true }, "self_approved": { "type": "boolean", "const": false } } }, "SignInRequest": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "The job's GitHub Actions OIDC token, requested with the audience assure; no credential examples are included" } } }, "SignedIn": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "key", "expires_at", "account_id" ], "properties": { "schema": { "type": "string", "const": "assure.serve.auth-oidc/v1" }, "key": { "type": "string", "pattern": "^asr_[0-9a-f]{8}_[A-Za-z0-9_-]{43}$", "description": "Shown once; send it as Authorization: Bearer until expires_at" }, "expires_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" }, "account_id": { "type": "string", "pattern": "^gh-[a-z0-9][a-z0-9-]{0,38}$" } } } ], "unevaluatedProperties": false }, "Failure": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "check_id", "outcome", "reason", "action", "detail", "charged" ], "properties": { "schema": { "type": "string", "const": "assure.serve.failure/v1" }, "check_id": { "type": [ "string", "null" ] }, "charged": { "type": "boolean", "description": "False on a refusal answered before a check was admitted; this sign-in route starts no checker." }, "request_id": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "The X-Request-Id of the request whose refusal was answered before a check was admitted (issue #1101); absent when the envelope names a check_id, as a typed failure of an admitted check does." }, "outcome": { "type": "string", "enum": [ "bad_input", "unauthenticated", "oversize_input", "rate_limited", "server_busy", "checker_error" ] }, "reason": { "type": "string" }, "action": { "type": "string" }, "build": { "type": "object", "required": [ "commit", "release_sha256", "checkers_sha256" ], "properties": { "commit": { "type": [ "string", "null" ] }, "release_sha256": { "type": [ "string", "null" ] }, "checkers_sha256": { "type": [ "string", "null" ] } }, "description": "Issue #1100: every freshly API-built refusal carries the serving engine's identity, including checker_error that refuses a development verdict; never copy the refused development block, kind or tree_sha256. Exactly commit, release_sha256 and checkers_sha256, the three keys of a verdict's engine block; all three are null if the engine pin fails verification. Compare build.commit first. Historical stored and non-API failures can omit this optional outer property and remain as originally written.", "additionalProperties": false }, "detail": { "type": "object", "properties": { "served_from": { "type": "string", "const": "handler", "description": "Issue #1665: every refusal on this route is minted while answering this request, so it is handler; this route reads no stored failure" }, "identity": { "type": "string", "enum": [ "malformed", "algorithm", "unknown_kid", "signature", "issuer", "audience", "expired", "not_yet_valid", "lifetime", "missing_claim", "owner_changed", "keys_unavailable" ] }, "rule": { "type": "string", "const": "oidc" }, "retry_after_s": { "type": "integer", "minimum": 1 }, "malformation": { "type": "object", "properties": { "kind": { "type": "string" }, "field": { "type": [ "string", "null" ] } } } } } } } ], "unevaluatedProperties": false }, "Verdict": { "type": "object", "required": [ "schema", "check_id", "profile", "outcome", "policy" ], "additionalProperties": true, "description": "The verdict envelope (VERDICTS.md). Fields not listed here are described there.", "properties": { "charged": { "type": "boolean", "description": "The check accounting flag on newly written server answers. Historical stored answers may omit it; a read-back preserves their bytes." }, "schema": { "const": "assure.serve.verdict/v1" }, "check_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "profile": { "type": "string" }, "outcome": { "type": "string" }, "policy": { "type": "object", "required": [ "exit" ], "properties": { "exit": { "type": "integer", "minimum": 0, "maximum": 125 }, "fail_on": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } } }, "upgrade": { "$ref": "#/components/schemas/Upgrade" }, "not_established": { "type": "array", "description": "One entry per obligation not established (VERDICTS.md section 9).", "items": { "type": "object", "additionalProperties": true, "properties": { "because": { "type": "object", "required": [ "gate", "premise", "source" ], "description": "Issue #1813, on postgresql-observed-baseline and python-auth-declared-model: which input sent the entry here. gate machine: the machine was refused or not read (premise the refusal reason, source the raw file it names); gate reading: the reading was not established (premise the declaration field or unobserved premise, an informational premise skipped, source raw/declaration.json# or the raw file). A part nothing names is null.", "properties": { "gate": { "enum": [ "machine", "reading" ] }, "premise": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } } } } } } }, "Upgrade": { "type": "object", "required": [ "url", "line" ], "additionalProperties": false, "description": "Present only when the account is on the free plan and the server has a Premium payment link, or when a gifted plan ends within 30 days and the server has that link. Absent on every other paid plan; its presence changes no other field. The Action prints it as the first line of the job summary.", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://buy\\.stripe\\.com/", "description": "The Premium Stripe Payment Link with your account id, URL-encoded, as client_reference_id" }, "line": { "type": "string", "description": "One plain sentence that ends with url" }, "notice": { "type": "string", "description": "Present only when the free plan's USD 1 balance, shared by reports and requirement compiling, is spent, or when a gifted plan ends within 30 days (\"Your gifted Premium plan ends on .\", and line is \"To keep it, upgrade at \"): one plain sentence, printed at the start of the upgrade line" } }, "example": { "url": "https://buy.stripe.com/?client_reference_id=gh-acme", "line": "Assure Premium checks your app's sign-in and session routes, not only the database. Upgrade for USD 20 a month: https://buy.stripe.com/?client_reference_id=gh-acme" } }, "Running": { "type": "object", "required": [ "check_id", "status" ], "additionalProperties": false, "properties": { "check_id": { "type": "string" }, "status": { "const": "running" } } }, "ProfileListing": { "type": "object", "required": [ "profiles", "limits", "engine", "not_served", "routes", "image" ], "additionalProperties": true, "description": "The GET /v1/profiles answer (serve/api.py public_profiles). Keys not listed here may be added; none listed is removed.", "properties": { "build": { "type": "object", "required": [ "commit", "release_sha256", "checkers_sha256" ], "properties": { "commit": { "type": [ "string", "null" ] }, "release_sha256": { "type": [ "string", "null" ] }, "checkers_sha256": { "type": [ "string", "null" ] } }, "description": "Issue #1100: the top-level serving engine identity, exactly commit, release_sha256 and checkers_sha256, the three keys of a verdict's engine block. Compare build.commit first to distinguish a deploy lag from a changed answer. All three values are null if the engine pin cannot be verified; no kind or tree_sha256 is served here. This block is beside profiles and limits and changes no profile row.", "additionalProperties": false }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileRow" } }, "limits": { "type": "object", "required": [ "body_bytes", "file_bytes", "files", "json_depth" ], "additionalProperties": true, "properties": { "body_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "files": { "type": "integer" }, "json_depth": { "type": "integer" } } }, "engine": { "type": "object", "description": "{commit, release}: the build that answers; both null while /healthz answers 503 engine_digest_mismatch." }, "not_served": { "type": "array", "description": "[{id, stack, waits_on}]: the planned profiles this server knows about and does not serve." }, "routes": { "type": "array", "description": "[{template, methods, free, rate_window, reads}]: the route table this server matches." }, "image": { "type": [ "object", "null" ], "description": "{files, manifest_sha256} of the built tree the server runs from, or null in a checkout." }, "served": { "type": "object", "description": "Bounded possible statuses per obligation, keyed by served profile id. Obligations follow the profile order and reachable statuses follow its precedence order. Profiles without computable obligations are omitted.", "additionalProperties": { "type": "object", "required": [ "obligations" ], "properties": { "obligations": { "type": "array", "items": { "type": "object", "required": [ "id", "reachable" ], "properties": { "id": { "type": "string" }, "reachable": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "ProfileRow": { "type": "object", "required": [ "id", "version", "inputs", "fail_on", "bias_default", "bias_classes", "obligations", "collector_pin", "progress_notes", "stacks" ], "additionalProperties": true, "description": "One served profile. The postgresql-declared-model row is pinned byte for byte (DIGEST-BASE) and carries stacks (issue #2650) but none of readings_shape, profile_sha256, collector, checker or docs. Keys not listed here may be added.", "properties": { "id": { "type": "string" }, "version": { "description": "The profile row's version." }, "inputs": { "type": "object", "required": [ "required", "optional" ], "description": "required: [{path, max_bytes}]; optional: [{path or pattern, max_bytes}]. A pattern must match the whole name." }, "fail_on": { "type": "object", "required": [ "accepted", "default", "not_collected" ], "properties": { "excluded_by_design": { "type": "array", "items": { "type": "string" }, "description": "The statuses the profile can emit that not_collected leaves out by design (needs_intent); absent from the postgresql-declared-model row." } }, "description": "The words ?fail_on= takes for this profile, the default, the statuses not collected and the statuses excluded by design." }, "bias_default": { "type": [ "string", "null" ], "description": "refute or prove, or null when the checker declares no bias classes." }, "bias_classes": { "type": [ "object", "null" ] }, "obligations": { "type": "array", "description": "[{id, machine, bias, security, observable_at_pin, class}]." }, "collector_pin": { "type": [ "string", "null" ] }, "progress_notes": { "description": "No served derive emits one; the 202 poll is the signal." }, "description": { "type": "string", "description": "The profile's words, when the row has them." }, "canonical_statements": { "type": "array", "description": "The declared profiles' canonical statements." }, "checker_entry_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "requirement_states": { "description": "mysql-declared-model only: the states each obligation can take." }, "scope": { "type": "object", "description": "{max_ids, binding[, records]}: only for a profile whose scope you select." }, "method_forms": { "type": "array", "description": "python-auth-declared-model only: [{form, lean_decidable, lean_decidable_when, consumers}]." }, "stacks": { "type": [ "array", "null" ], "description": "The identity stacks the registry wires to the profile's checker (for python-auth-declared-model also to the python/fastapi, python/django (issue #266) and python/stdlib-http (issue #3840) adapters its free route runs; for a checker that runs a shared identity adapter as its leg, that adapter's row, issue #3495), or the database/endpoint kind (database/postgresql, database/mysql, endpoint/http) for the PostgreSQL, MySQL and HTTP profiles; on every row, the pinned one included (issue #2650). null for a registry-wired row when the server holds no readable adapter registry." }, "readings_shape": { "enum": [ "wrapped", "flat" ], "description": "How scope_binding is sent; absent from the pinned row." }, "profile_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The sha256 of the profile row file's bytes: the same digest a verdict for this profile carries as profile_sha256 (issue #2072). Absent from the pinned row." }, "collector": { "type": "object", "required": [ "status", "file" ], "additionalProperties": false, "properties": { "status": { "enum": [ "pinned", "none", "malformed" ] }, "file": { "type": [ "string", "null" ] } }, "description": "The registered collector claim: pinned, none or malformed, with its file when known. Absent from the pinned PostgreSQL row." }, "checker": { "type": "object", "required": [ "id", "package", "derive_path" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "package": { "type": [ "string", "null" ] }, "derive_path": { "type": [ "string", "null" ] } }, "description": "The checker registry id, package and server derive path. Absent from the pinned PostgreSQL row." }, "docs": { "type": "object", "required": [ "quickstart_section" ], "additionalProperties": false, "properties": { "quickstart_section": { "type": "integer", "minimum": 1, "maximum": 999 } }, "description": "The quick-start section named by the profile row, when present. Absent from the pinned PostgreSQL row." } } }, "Failure_checks": { "type": "object", "required": [ "schema", "outcome", "reason", "action" ], "additionalProperties": true, "properties": { "charged": { "type": "boolean", "description": "The check accounting flag on newly written server answers. Historical stored answers may omit it; a read-back preserves their bytes." }, "schema": { "const": "assure.serve.failure/v1" }, "request_id": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "The X-Request-Id of the request, on a refusal answered before a check was admitted (check_id null; issue #1101); absent when the envelope names a check_id." }, "detail": { "type": "object", "additionalProperties": true, "properties": { "served_from": { "enum": [ "handler", "store" ], "description": "Where the API served this failure from (issue #1665): handler when minted while answering this request, store when it is the admitted check's stored failure, first answered or read back." } } }, "outcome": { "type": "string" }, "reason": { "type": "string" }, "action": { "type": "string" }, "build": { "type": "object", "required": [ "commit", "release_sha256", "checkers_sha256" ], "properties": { "commit": { "type": [ "string", "null" ] }, "release_sha256": { "type": [ "string", "null" ] }, "checkers_sha256": { "type": [ "string", "null" ] } }, "description": "Issue #1100: every freshly API-built refusal carries the serving engine's identity, including checker_error that refuses a development verdict; never copy the refused development block, kind or tree_sha256. Exactly commit, release_sha256 and checkers_sha256, the three keys of a verdict's engine block; all three are null if the engine pin fails verification. Compare build.commit first. Historical stored and non-API failures can omit this optional outer property and remain as originally written.", "additionalProperties": false } } }, "Rotated": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "key_id", "key", "expires_at", "account_id", "predecessor", "reissued" ], "properties": { "schema": { "type": "string", "const": "assure.serve.keys.rotate/v1" }, "key_id": { "type": "string", "pattern": "^[0-9a-f]{8}$" }, "key": { "type": "string", "description": "The successor key, asr__; shown here and never stored" }, "expires_at": { "type": "string", "description": "ISO time, UTC, 30 days from the first rotate" }, "account_id": { "type": "string" }, "predecessor": { "type": "object", "additionalProperties": false, "required": [ "key_id", "expires_at" ], "properties": { "key_id": { "type": "string" }, "expires_at": { "type": "string", "description": "When the presented key stops working" } } }, "reissued": { "type": "boolean", "description": "true when this successor was minted by an earlier rotate inside the overlap" } } } ], "unevaluatedProperties": false }, "Failure_keys": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "check_id", "outcome", "reason", "action", "detail", "charged" ], "properties": { "schema": { "type": "string", "const": "assure.serve.failure/v1" }, "check_id": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "The X-Request-Id of the request whose refusal was answered before a check was admitted (issue #1101); every refusal on this route is answered before any check, so check_id is null and request_id is present (REFUTATION-r3 H2)." }, "outcome": { "type": "string", "enum": [ "bad_input", "unauthenticated", "key_expired", "rotate_too_early", "rate_limited", "checker_error" ] }, "reason": { "type": "string" }, "action": { "type": "string" }, "detail": { "type": "object", "properties": { "served_from": { "type": "string", "const": "handler", "description": "Issue #1665: every refusal on this route is minted while answering this request, so it is handler" }, "opens_at": { "type": [ "string", "null" ], "description": "rotate_too_early: when the window opens; null for a key with no expiry yet, and for a GitHub sign-in key, which never rotates (the reason says which)" }, "expires": { "type": "string", "description": "rotate_too_early and key_expired: the presented key's expiry" }, "window": { "type": "string", "enum": [ "minute", "day" ] }, "retry_after_s": { "type": "integer", "minimum": 1 }, "malformation": { "type": "object" }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "405: the methods the route takes" }, "route": { "type": "string", "description": "405: the route template" } } }, "charged": { "type": "boolean", "const": false, "description": "No check is admitted by the rotation route; every refusal is uncharged." }, "build": { "type": "object", "required": [ "commit", "release_sha256", "checkers_sha256" ], "properties": { "commit": { "type": [ "string", "null" ] }, "release_sha256": { "type": [ "string", "null" ] }, "checkers_sha256": { "type": [ "string", "null" ] } }, "description": "Issue #1100: every freshly API-built refusal carries the serving engine's identity, including checker_error that refuses a development verdict; never copy the refused development block, kind or tree_sha256. Exactly commit, release_sha256 and checkers_sha256, the three keys of a verdict's engine block; all three are null if the engine pin fails verification. Compare build.commit first. Historical stored and non-API failures can omit this optional outer property and remain as originally written.", "additionalProperties": false } } } ], "unevaluatedProperties": false }, "Kind": { "type": "string", "enum": [ "friction", "wrong_reading", "coverage_gap", "model_proposal_intent" ], "description": "wrong_reading: agent names obligation and expected reading in text. coverage_gap: names missing profile/rule. model_proposal_intent: intent only; model submissions await Director licensing/ownership decision and later qualification gates." }, "Package": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100, "description": "No Unicode control characters" }, "version": { "type": "string", "maxLength": 100, "default": "", "x-max-utf8-bytes": 100, "description": "No Unicode control characters" } } }, "Agent": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "model_id": { "type": "string", "maxLength": 100, "default": "", "x-max-utf8-bytes": 100, "description": "No Unicode control characters" }, "client": { "type": "string", "maxLength": 100, "default": "", "x-max-utf8-bytes": 100, "description": "No Unicode control characters" } } }, "FeedbackRequest": { "type": "object", "additionalProperties": false, "required": [ "kind", "text" ], "properties": { "kind": { "$ref": "#/components/schemas/Kind" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "x-max-utf8-bytes": 4096, "description": "1..4096 UTF-8 bytes; valid Unicode without lone surrogates or Unicode control characters except LF and TAB. Customer data, never instructions" }, "check_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{32}$", "default": null }, "profile": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "default": null }, "profile_wanted": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "default": null, "description": "the profile a coverage_gap note wishes existed; the daily digest counts notes by it" }, "obligation": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,64}$", "default": null }, "package": { "$ref": "#/components/schemas/Package" }, "agent": { "$ref": "#/components/schemas/Agent" }, "consent_follow_up": { "type": [ "boolean", "null" ], "default": false, "description": "null normalises to false; true permits follow-up" } } }, "Accepted": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "id", "received_at", "kind", "check_id", "profile", "obligation", "package", "sha256", "duplicate", "related", "routed" ], "properties": { "schema": { "type": "string", "const": "assure.serve.feedback/v1" }, "id": { "type": "string", "pattern": "^fb-[0-9]{8}-[0-9a-f]{16}$" }, "received_at": { "type": "string", "format": "date-time" }, "kind": { "$ref": "#/components/schemas/Kind" }, "check_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{32}$", "description": "the stored row's check id" }, "profile": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "description": "the stored row's profile" }, "obligation": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,64}$", "description": "the stored row's obligation" }, "package": { "$ref": "#/components/schemas/Package" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "the stored row's deduplication digest, sha256 of kind|check_id|text (not of the text alone); on a duplicate, the first row's. Text itself is not echoed." }, "duplicate": { "type": "boolean" }, "related": { "type": "array", "maxItems": 10, "description": "this account's other notes of the same kind and profile (match kind+profile) whose status is not merged or declined, among its notes of the newest 7 UTC-day files, newest first; when the note has no profile, the open notes of the same kind of any profile, null included (match kind; issues #1626, #2125)", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "kind", "profile", "status", "match" ], "properties": { "id": { "type": "string", "pattern": "^fb-[0-9]{8}-[0-9a-f]{16}$" }, "kind": { "$ref": "#/components/schemas/Kind" }, "profile": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "status": { "type": "string", "enum": [ "received", "in_pr", "unavailable" ] }, "match": { "type": "string", "enum": [ "kind+profile", "kind" ] } } } }, "routed": { "type": "object", "additionalProperties": false, "required": [ "digest", "status_route", "next" ], "description": "where the note goes next (issue #2125)", "properties": { "digest": { "type": "string", "pattern": "^Agent feedback digest [0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "the daily agent feedback digest that reads the note, by its UTC day" }, "status_route": { "type": "string", "pattern": "^GET /v1/feedback/fb-[0-9]{8}-[0-9a-f]{16}$", "description": "the route that answers the note's state" }, "next": { "type": "string", "description": "one sentence naming the digest and the status route" } } } } } ], "unevaluatedProperties": false }, "Stored": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "id", "ts", "account_id", "key_id", "kind", "check_id", "check_known", "profile", "obligation", "package", "agent", "consent_follow_up", "text", "sha256", "rows_unreadable", "status" ], "properties": { "schema": { "type": "string", "const": "assure.serve.feedback/v1" }, "id": { "type": "string", "pattern": "^fb-[0-9]{8}-[0-9a-f]{16}$" }, "ts": { "type": "string", "format": "date-time" }, "account_id": { "type": "string" }, "key_id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/Kind" }, "check_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{32}$" }, "check_known": { "type": "boolean" }, "profile": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "profile_wanted": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$", "description": "absent on notes stored before issue #1248" }, "obligation": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "package": { "$ref": "#/components/schemas/Package" }, "agent": { "$ref": "#/components/schemas/Agent" }, "consent_follow_up": { "type": "boolean" }, "text": { "type": "string", "minLength": 1, "x-max-utf8-bytes": 4096 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "rows_unreadable": { "type": "integer", "minimum": 0 }, "status": { "$ref": "#/components/schemas/Status" } } } ], "unevaluatedProperties": false }, "Status": { "type": "object", "required": [ "state", "pr", "release", "reason", "updated_at" ], "additionalProperties": false, "description": "The note's state, set by Symbolia as it acts on the note: received (the default), in_pr (pr), merged (release, the engine commit that ships the change; pr optional) or declined (reason); unavailable (with a reason) when the state cannot be read just now.", "properties": { "state": { "type": "string", "enum": [ "received", "in_pr", "merged", "declined", "unavailable" ] }, "pr": { "type": [ "integer", "null" ], "minimum": 1 }, "release": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{40}$" }, "reason": { "type": [ "string", "null" ], "minLength": 1, "x-max-utf8-bytes": 300 }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Failure_feedback": { "allOf": [ { "$ref": "#/components/schemas/Flags" }, { "type": "object", "required": [ "schema", "check_id", "outcome", "charged", "reason", "action", "detail" ], "properties": { "schema": { "type": "string", "const": "assure.serve.failure/v1" }, "check_id": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "pattern": "^[0-9a-f]{16}$", "description": "The X-Request-Id of the request whose refusal was answered before a check was admitted (issue #1101); absent when the envelope names a check_id, as a typed failure of an admitted check does." }, "outcome": { "type": "string", "enum": [ "bad_input", "unauthenticated", "key_expired", "oversize_input", "rate_limited", "not_found", "checker_error" ] }, "charged": { "type": "boolean", "description": "Whether this request was charged; feedback routes do not run a check." }, "reason": { "type": "string" }, "action": { "type": "string" }, "build": { "type": "object", "required": [ "commit", "release_sha256", "checkers_sha256" ], "properties": { "commit": { "type": [ "string", "null" ] }, "release_sha256": { "type": [ "string", "null" ] }, "checkers_sha256": { "type": [ "string", "null" ] } }, "description": "Issue #1100: every freshly API-built refusal carries the serving engine's identity, including checker_error that refuses a development verdict; never copy the refused development block, kind or tree_sha256. Exactly commit, release_sha256 and checkers_sha256, the three keys of a verdict's engine block; all three are null if the engine pin fails verification. Compare build.commit first. Historical stored and non-API failures can omit this optional outer property and remain as originally written.", "additionalProperties": false }, "detail": { "type": "object", "properties": { "served_from": { "type": "string", "const": "handler", "description": "Issue #1665: every refusal on this route is minted while answering this request, so it is handler; this route reads no stored failure" }, "window": { "type": "string", "enum": [ "minute", "day" ] }, "retry_after_s": { "type": "integer", "minimum": 1 }, "accepted_fields": { "type": "array", "items": { "type": "string" }, "description": "bad_input from the feedback body: the accepted top-level keys, sorted" }, "kinds": { "type": "array", "items": { "$ref": "#/components/schemas/Kind" }, "description": "bad_input from the feedback body: the accepted values of kind" }, "shapes": { "type": "object", "description": "bad_input from the feedback body: each accepted top-level key's form, text, boolean, the list of kinds, or an object of its keys (package {name, version}, agent {model_id, client})" }, "example": { "$ref": "#/components/schemas/FeedbackRequest", "description": "bad_input from the feedback body: one minimal valid body, the request example" }, "malformation": { "type": "object", "properties": { "kind": { "type": "string" }, "file": { "type": [ "string", "null" ] }, "line": { "type": [ "integer", "null" ] }, "field": { "type": [ "string", "null" ] }, "expected": { "type": "string" }, "pointer": { "type": "string", "pattern": "^(/([A-Za-z0-9_.-]|~1)+)+$" } } } } } } } ], "unevaluatedProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Valid unrevoked Assure API key; no credential examples are included" }, "bearer": { "type": "http", "scheme": "bearer" } }, "responses": { "Verdict": { "description": "The check finished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verdict" } } } }, "Running": { "description": "The check is still running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Running" } } } }, "Failure": { "description": "A typed outcome (QUICKSTART-API.md, section 9)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_checks" } } } }, "BadInput": { "description": "bad_input: malformed JSON, body, header or unsupported query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "Unauthenticated": { "description": "unauthenticated: absent, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "MethodNotAllowed": { "description": "bad_input: method not allowed; detail.allowed lists the route's methods (the same list as Allow) and detail.route names the route", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "OversizeInput": { "description": "oversize_input: body exceeds 16384 bytes; text field size violations are bad_input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "NotFound": { "description": "not_found: no feedback note with that id exists for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } }, "CheckerError": { "description": "checker_error: server failed while answering; feedback storage failure does not affect checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Failure_feedback" } } } } } } }