Quickstart: the Assure API

Served today: five profiles. postgresql-observed-baseline: intent-free, from a connection or an artefacts directory. postgresql-declared-model: an artefacts directory (raw/declaration.json) or a connection with .assure/declaration.json. http-observed-baseline: an artefacts folder holding an endpoint manifest and captured response heads; the Action produces the scope binding and passes the identity key by pipe. mysql-declared-model: a MySQL server, from a mysql:// connection plus your declaration file (declaration), or an artefacts directory holding raw/submission.json; reports are withheld (profile_unqualified) until the writer is qualified for MySQL. python-auth-declared-model: a Python (Flask) repository, free, from the checkout in one step; the Action proposes a drafted declaration in a pull request the merge accepts; FastAPI, Django and standard-library http.server repositories with your declaration.

The API runs the checker on Symbolia's server. The Assure GitHub Action is a client of this API. You send collected files. You get back a verdict.

Base URL: https://api.symbolia.ai

For a first verdict on one page, see FIRST-RUN-API.md.

1. Get a key

From a GitHub Actions workflow you need no stored key: sign in with the workflow's GitHub identity. Give the job permissions: id-token: write (keep contents: read beside it), request the job's OIDC token with the audience assure, and send it to POST /v1/auth/oidc as {"token": "<the token>"}. The answer is {schema, key, expires_at, account_id} with the seven flags: a key for the account gh-<your GitHub owner, lower case>, created on the free plan the first time it signs in, that expires at the token's own expiry or one hour from now, whichever comes first. The Action does this for you when its api-key input is empty. A token that does not verify is refused unauthenticated (401), with detail.identity naming the check that failed (malformed, algorithm, unknown_kid, signature, issuer, audience, expired, not_yet_valid, lifetime, missing_claim or owner_changed); while GitHub's signing keys cannot be read the answer is server_busy (503) with detail.identity: keys_unavailable and Retry-After: 60. The token and the key are never logged or stored; only the key's hash is kept.

Otherwise, Symbolia issues keys by hand. Ask Symbolia for a key, and you receive it once over a private channel. Symbolia keeps only a hash of it. If you lose it, ask for a new one; the old one is revoked.

Rotate a stored key with POST /v1/keys/rotate during its rotation window (section 1). There is no route to revoke a key and no assure login command: the API reads a key only from the Authorization header. A GitHub sign-in key lasts at most an hour and never rotates; sign in again for a new one. Ask Symbolia to issue or revoke a stored key.

Keep the key in an environment variable. The examples below read it from $ASSURE_API_KEY.

Send it on every request except /healthz:

Authorization: Bearer $ASSURE_API_KEY

A key expires 30 days after it is issued, or within the hour for a key from the GitHub sign-in. A key issued before expiry existed has no expiry until Symbolia gives it one, 30 days from that day; until then it is not refused for its age, and its answers carry no Assure-Key-Expires header. Each answer to a keyed request whose key has an expiry carries the header Assure-Key-Expires: <ISO time, UTC>, except an answer sent before the key is read, which names no expiry: not_found (no such route), a 405 (a method the route does not allow), a 400 for a malformed request line or headers, a checker_error raised while the key store is read, and the refusal unauthenticated (a missing, wrong or revoked key). A 200 or any other keyed answer without the header means the key has no expiry yet. From 14 days before that time, the answer also carries Assure-Key-Warning, one line naming the date and how to rotate, and the Action's job summary carries the same line. A key past its expiry is refused key_expired (section 9). From 7 days before it expires (day 23 of a 30-day key, or the last quarter of a shorter key Symbolia issued), POST /v1/keys/rotate with the key answers its successor: {schema, key_id, key, expires_at, account_id, predecessor: {key_id, expires_at}, reissued}, a new 30-day key for the same account and plan. The old key keeps working until its own Assure-Key-Expires (the overlap), so an agent can rotate itself in time and keep working; a second rotate with the old key inside the overlap answers the same successor (reissued true). Before the window the rotate is refused rotate_too_early (409) with detail.opens_at, the time it opens. A GitHub sign-in key never rotates: it lives for its run only (at most one hour), its rotate is refused rotate_too_early with detail.opens_at null, and the next run signs in again for its own key. The rotate route is described in the keys OpenAPI contract.

2. Collect

The API never connects to your database. You collect the files first, on a machine that can reach the server.

The collector is action/collector/collect_pg.py in the public Symbolia-Assurance/assure-action repository. Fetch it from the beta branch:

git clone https://github.com/Symbolia-Assurance/assure-action assure-action
git -C assure-action checkout beta

Create the collection role as in QUICKSTART-ACTION.md, section 2. Set the standard libpq variables (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGSSLMODE), then run:

python3.14 -B collect_pg.py --out out \
  --role assure_collector \
  --privileges pg_read_all_settings,pg_read_all_stats \
  --data-dir /var/lib/postgresql/18/main

--data-dir must be a directory this machine can read. If the server keeps its configuration files outside the data directory (the Debian layout uses /etc/postgresql/<major>/<cluster>), add --extra-root <that directory>, once per directory. The collector reads configuration files only inside these directories. Run it from assure-action/action/collector/, or give its path. Exit 0 or 1 means the output is ready to send (1: with gaps the sidecar names); the flags and the exit codes are in the Action quick start, section 9, under "Running the collector yourself".

After a change to the server, collect again into a new directory and send the new files. A resend with the same Idempotency-Key returns the stored verdict (section 4), never a reading of the changed server.

Then gather the checker's inputs into one raw/ folder:

mkdir -p bundle/raw
cp -R out/raw/. bundle/raw/
cp out/COLLECTION-SIDECAR.json out/TIMING.json bundle/raw/

Always send raw/COLLECTION-SIDECAR.json. The collector the Action ships writes a rule or setting it cannot keep safely as a marker line, !collect_pg-withheld line N reason CODE, which the check reads as not observed. The earlier collector writes such a line as # [collect_pg: line withheld, ...], and the sidecar is its record of why. A configuration file that holds such a line, sent without the sidecar or without the sidecar's record of that file, is refused with collector_refused (422) and not charged: a collector output without its sidecar cannot be checked. A pg_hba.conf rule with a quoted name, an @file list or a regular-expression user (/^...) is one the earlier collector withholds whole; Assure cannot read it, and the same refusal names the file and the line. The collector the Action ships keeps such rules as written. If you cannot collect again: remove quotes a name does not need; write an @file list's names inline; use a +group role in place of a list; list a regular-expression user's roles by name. Otherwise, send Symbolia the file name and the line number through your Symbolia contact, so the shape is counted.

Send the collector's own output from one run: raw/ and the COLLECTION-SIDECAR.json the collector wrote with it, never a sidecar kept from an earlier run or taken from another collection. You are responsible for this when you call the API directly. The sidecar counts the lines the collector withheld; it does not say which line is which, so a sidecar from another run could count a withheld rule as a comment, and the API cannot tell. The GitHub Action checks this binding in your runner, before it sends anything: it reads the collector's REDACTION-MANIFEST.json (written beside raw/ in the same run), checks that its digest of each file holding a withheld line equals the file as collected and that it records the same withheld lines as the sidecar, and stops otherwise. That check catches records from another run only when a file that holds a withheld line differs, byte for byte, from that run's file (DATA.md states the limit). The API cannot repeat that check, because the files it receives from the Action have their comments withheld and no longer match the collector's digests. Do not send REDACTION-MANIFEST.json; it is not an accepted name.

From PostgreSQL 16, a pg_hba.conf line ending in \ continues on the next line. If raw/declaration.json gives a major on the other side of 16 from the one the sidecar records, and a pg_hba.conf line ends in \, the request is refused with bad_input (400). Set the declaration's major to the server's major.

MySQL: collect_mysql.py

For mysql-declared-model the collector is action/collector/collect_mysql.py, beside collect_pg.py in the assure-action checkout above. It reads the server through the mysql client with fixed SELECT and SHOW statements only, takes your declaration file (--declaration; schema symbolia.mysql-declaration.v0, the file the Action's declaration input names) and folds it into one file, out/raw/submission.json, which is the whole upload: there is no bundle/raw step and no sidecar. The Action runs it for you from a mysql:// connection; run yourself, the connection reaches it by the client's environment (MYSQL_HOST, MYSQL_TCP_PORT and MYSQL_PWD, or MYSQL_UNIX_PORT for a socket), never on a command line:

MYSQL_HOST=db.example MYSQL_TCP_PORT=3306 MYSQL_PWD="$COLLECTOR_PASSWORD" \
python3.14 -I -B collect_mysql.py --out out \
  --role assure_collector \
  --declaration mysql-declaration.json \
  --mysql mysql

All four flags are required: --role is the collection role, which is also the user the client logs in as unless --login-user names another; --mysql is the client program to run. Exit 0 or 1 means out/raw/submission.json is ready to send (1: with recorded gaps); exit 3 writes out/REFUSAL.json and nothing else. Section 3 lists the file's top-level keys with the machine that needs each, so you can read what the collector wrote before you send it.

3. Input files

To see what a profile reads before you collect your own, FIXTURES.md lists, for each profile, the committed fixtures, the first line each one reads, sample verdicts (one with refused machines) and a sample declaration for each declared profile.

Send only the files the profile reads. GET /v1/profiles lists, for each profile, the required names, the accepted names and patterns, and each one's size limit. postgresql-declared-model requires raw/catalog_snapshot.json and raw/declaration.json. postgresql-observed-baseline requires raw/catalog_snapshot.json only, but its check must also observe the server's major version: send raw/COLLECTION-SIDECAR.json (its server.server_version_num) from the same collection, or raw/command_line.json and a catalog_snapshot.json with its roles section, whose two readings agree. Without them the check is refused profile_refused with detail.kind major_not_observed, and that refusal is counted and charged; POST /v1/lint (section 6) reports it first, free, as a files finding naming raw/COLLECTION-SIDECAR.json with field major_not_observed. A catalog_snapshot.json with none of the sections the collector writes (collection, roles, ...) is not a snapshot: lint names it and the check refuses it before admission, uncharged; send collect_pg.py's own output. The collector produces:

A missing configuration file makes the readings that need it read not observed or representation. A missing catalog snapshot stops the check. A name the profile does not accept is bad_input.

MySQL: raw/submission.json

mysql-declared-model requires one file, raw/submission.json, and accepts no other name: raw/declaration.json is not accepted by mysql-declared-model (the collector folds your declaration into the submission), and sending it is bad_input. The file is one JSON object; its top-level keys are the ones collect_mysql.py writes, listed here with the machine that refuses (representation) without each one. A key not in this list is carried, not projected, and read by no machine; a key the list has but the file lacks makes the machines that require it read representation, so a hand-built file that stops at the envelope (the first four rows) yields representation on every machine, and one that adds only mysql_user yields verdicts on M2 alone. M3 and M4 also require model_revisions (and M4 an M4 section) that collect_mysql.py does not write, so those two read representation from the collector's output today.

The collector that produces it is action/collector/collect_mysql.py in the assure-action repository fetched in section 2, beside collect_pg.py; section 2's MySQL sub-step gives its command. It reads the server through the mysql client with fixed SELECT and SHOW statements only, and takes your declaration file, schema symbolia.mysql-declaration.v0, whose declared sections it carries verbatim. The Action runs it for you from a mysql:// connection; run yourself, the connection reaches it by the client's environment (MYSQL_HOST, MYSQL_TCP_PORT and MYSQL_PWD, or MYSQL_UNIX_PORT for a socket), never on a command line. Send its out/raw/submission.json as raw/submission.json and nothing beside it, with "profile": "mysql-declared-model" in the request body: section 4's example says postgresql-declared-model and its first script reads bundle/, which a MySQL collection does not have, so build the body with section 4's MySQL script, which reads the collector's out/; under postgresql-declared-model, raw/submission.json is bad_input. The check reads the file and contacts no server. A report for it is withheld with profile_unqualified until the report writer is qualified for MySQL.

4. Submit a check

For postgresql-declared-model, you write the declaration yourself: the collector does not produce it. Write declaration.json as DECLARATIONS.md describes: schema assure.postgresql.declaration/v1, with the required fields schema, id and major (major is the server's major version, which section 2 says the declaration must match). Validate it free, with no API key or network, from the assure-action checkout fetched in section 2: python3.14 -B -m action.declare validate /path/to/declaration.json (exit 0: valid structure; exit 2: invalid input). Then add it to the bundle, for postgresql-declared-model only:

cp declaration.json bundle/raw/declaration.json

This step is for postgresql-declared-model only: mysql-declared-model accepts no raw/declaration.json (section 3: the collector folds the declaration into raw/submission.json), and postgresql-observed-baseline takes one only to tighten a baseline.

POST /v1/checks with a JSON body of two keys, profile and files:

{
  "profile": "postgresql-declared-model",
  "files": {
    "raw/catalog_snapshot.json": "<base64 of the file>",
    "raw/declaration.json": "<base64 of the file>",
    "raw/pg_hba.conf": "<base64 of the file>"
  }
}

This builds the body from bundle/ with standard tools. Set PROFILE once to the profile you are checking, one of the two below; the script puts it in the body's profile:

PROFILE=postgresql-declared-model        # a declared bundle, with raw/declaration.json (above)
# PROFILE=postgresql-observed-baseline   # an observed bundle (section 2); no raw/declaration.json needed

cd bundle
{
  printf '{"profile":"%s","files":{' "$PROFILE"
  sep=''
  find raw -type f | LC_ALL=C sort | while IFS= read -r name; do
    printf '%s"%s":"%s"' "$sep" "$name" "$(base64 < "$name" | tr -d '\n')"
    sep=','
  done
  printf '}}'
} > ../request.json
cd ..

For mysql-declared-model there is no bundle/: build the body from the collector's --out directory, out/ in section 2's command, which holds raw/submission.json and nothing else to send:

printf '{"profile":"mysql-declared-model","files":{"raw/submission.json":"%s"}}' \
  "$(base64 < out/raw/submission.json | tr -d '\n')" > request.json

Either way, send request.json:

curl -sS https://api.symbolia.ai/v1/checks \
  -H "Authorization: Bearer $ASSURE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  --data-binary @request.json \
  -o response.json -w '%{http_code}\n'

The server needs Content-Length; --data-binary @file sets it. Chunked bodies are refused.

Choosing what fails: fail_on

Add ?fail_on=<words> to the URL to set which statuses give policy.exit 1. The default is fails. The server checks every word against the profile; a word the profile cannot emit is bad_input, its reason lists the accepted words, and nothing is charged. GET /v1/profiles lists each profile's words under fail_on.

• Any status the profile can emit except holds and vacuous.
• not_collected: every status the profile uses for a fact it could not read or represent. For postgresql-declared-model that is representation, missing_method, missing_premise and not_evaluated. For postgresql-observed-baseline it is representation, missing_method, not_observed and missing_baseline; needs_intent is out of scope by design, so name it on its own to fail on it.
• never, on its own: no reading gives exit 1, except a prove-class obligation that is not proven (exit 1, not_proven).

curl -sS 'https://api.symbolia.ai/v1/checks?fail_on=fails,not_collected' ...

• unresolved-security: strict, never the default. It stands for fails and also fails on every obligation the checker marks security: true that has no verdict on a machine that was read. The observed PostgreSQL profile marks 37 of its 41 obligations security: true; the declared PostgreSQL profile marks 4 of its 40 obligations security: true (M5 RLS-1 to RLS-4, the row-level security rows), so an unresolved RLS row on a machine that was read turns the run red; the HTTP profile marks none, so for it strict changes nothing. Only the security obligations the pinned collector can observe count in n and m: an obligation the profile marks observable_at_pin: false is listed as not established, "not observable at collector pin <pin>", and the first line says "strict: n of m security obligations observable at this pin". An intent-bound obligation (class: intent_bound) depends on what the system is for, which no collector observes. All security obligations without a verdict bind under strict, including one the pin cannot observe; the report names each and why. An intent-bound one is named "unresolved by your choice (strict)", reads "depends on what the system is for" and has the action "state it in requirements.md". n and m count observability only: an intent-bound obligation never counts in them and is never listed as not observable at the collector pin; m counts the intent-free security obligations. GET /v1/profiles lists each obligation's security mark, its observable_at_pin, its class (intent_bound or intent_free) and its bias class, bias: refute (green unless disproven) or prove (red unless proven). On postgresql-observed-baseline each obligation also lists majors_pinned, the sorted PostgreSQL majors (integers) at which every baseline row the obligation needs is pinned in the profile's baseline set (for example HBA-1-OB lists [17, 18]: its trust and listen rows have no pinned page for 15 or 16); at a major outside the list that obligation can read missing_baseline. A row that applies only under a condition does not narrow the list; an obligation that needs no baseline row lists every major the set documents. The other profiles list no majors_pinned. Its top-level served.<pid>.obligations lists each obligation's reachable statuses; one whose reachable lacks holds and fails never binds fail_on with fails (VERDICTS.md).

Partial reads: allow_partial

The verdict's machines field lists the machines the checker read and those it could not read, each with the checker's reason. A run in which some machines could not be read is green (policy.exit 0, policy.reason nothing_disproven) unless something is disproven; the first line names what was not read. allow_partial=1 and allow_partial=0 are still accepted and give the same result. Any other value is bad_input, and nothing is charged.

curl -sS 'https://api.symbolia.ai/v1/checks?fail_on=fails&allow_partial=1' ...

A selected scope: scope, scope_binding, accepted_scope_ref

Both PostgreSQL profiles check a fixed scope (their machines) and take none of these three body fields; sending one is bad_input. They are for a profile whose scope you select, which GET /v1/profiles marks with scope: {max_ids, binding[, records]}:

• scope: the list of selected ids, 1 to max_ids distinct ids of A-Z, a-z, 0-9, _, . and -.
• scope_binding: when binding names a map, an object whose keys are exactly that map and every name in records. The map maps every id in scope (no more, no fewer) to its own token of 1 to 63 characters of A-Z, a-z, 0-9, ., _ and -, beginning with a letter or digit. Each record is a JSON object whose schema is the one the profile expects; a record that names ids per key names exactly the ids in scope. A record may not carry key material: no key named like key, secret, hmac_key, private_key, signing_key, api_key, password or passphrase (in any case or spelling with -, _ or .), and no value or key that looks like a key: a run of 48 or more hex characters (also when written with : or - between them, or in fullwidth form), or 40 or more base64 characters of mixed case. A lower-case 64-character hex digest is accepted only as the value for a selected id in the one field the profile names for per-id digests (for the HTTP profile, endpoint_digests), whose keys are exactly your selected ids. In that position Assure cannot tell a key from a digest, so such a value reaches the server's work directory; what catches a value that is not your runner's digest is the checker's comparison with the digests in the collector's record. Shorter keys (under 48 hex or 40 base64 characters), base64url keys split by - or _, base32 keys and hex split by spaces, dots or line breaks are not caught: the check is a fixed list of encodings. The per-id digest field is the only object in a record keyed by your selected ids: any other object keyed by them is refused, as is one keyed by only some of them. For http-observed-baseline, every id has the form endpoint-[0-9]{3} and every token the form [a-z][a-z0-9-]{0,62}, the forms its checker reads; anything else is bad_input before the check runs. Every value of endpoint_digests must be 64 lower-case hex characters, the digest the collector wrote: a value that looks like a key (the shapes above, so also 64 upper-case hex) is refused as key material, and any other value is bad_input with a reason naming the record and the field (every value of scope_binding.identity_binding.endpoint_digests must be 64 lower-case hex characters), never the id or the value sent. That is the one field of the record whose form is checked before the check runs; the record's other fields (algorithm, key_id, and any key beside the four the collector writes) are carried as sent, and a value the checker refuses there is answered as checker_error, so send the record exactly as the collector wrote it. The GitHub Action makes this whole object for you from your endpoint manifest. A key stays in your runner; a record names it only by its key_id. Required when the profile names a map; refused when it names none.
• accepted_scope_ref: refused for now. No accepted scope record can be resolved yet, so send none; without it the check is a first-run comparison.

A refusal of any of them is bad_input with detail.malformation.kind scope_missing, scope_binding or scope_ref; a scope_binding refusal's detail.malformation.pointer is the JSON pointer of the key it stopped on (/scope_binding, /scope_binding/<map>, /scope_binding/<map>/<id> for one id's token, or /scope_binding/<record> or /scope_binding/<record>/<field> for a binding record the reason names; the reason never quotes the id). It is answered before any check starts: it is never charged, and it counts against your rate limits. The three fields are part of the request, so a resend with the same Idempotency-Key and a changed field is bad_input.

For http-observed-baseline the body carries the selected endpoints and their binding beside the files:

{
  "profile": "http-observed-baseline",
  "files": {"raw/HTTP-FACTS.json": "<base64>", "raw/COLLECTION-SIDECAR.json": "<base64>",
            "raw/response-heads/endpoint-001.txt": "<base64>"},
  "scope": ["endpoint-001"],
  "scope_binding": {
    "endpoint_tokens": {"endpoint-001": "<scope token>"},
    "identity_binding": {"schema": "assure.http.endpoint-identity.v1", "algorithm": "hmac-sha256",
                         "key_id": "<key id>", "endpoint_digests": {"endpoint-001": "<64 lower-case hex>"}}
  }
}

The Action produces this binding for you: it runs the identity producer and the HTTP collector in your runner with a fresh key on a pipe (the Action quick start, section 12). A direct API caller produces the same record with its own key, kept in its runner, by running the same two programs itself; the next subsection shows how.

Collecting for http-observed-baseline: the producer and the collector

The HTTP profile has no connection and no collect_pg.py step. You write an endpoint manifest, capture each endpoint's response head, and run two programs over that folder with one key on a pipe. The folder is the one the Action quick start, section 12, describes: manifest.json with "schema_version": "http-fixture-001", "mode": "offline_fixture", the seven flags and endpoints (each with id, scope_token, scheme, host, port, path, response_file and complete), beside one head file per endpoint captured with curl -sS --http1.1 -I. Section 12 gives a complete manifest.json for two endpoints and the capture commands; the examples below use its layout, a folder named http-fixture.

The two programs are in the assure-action checkout of section 2, under action/http/:

• action/http/action_identity_fixture.py, the identity producer. It reads manifest.json (never a head file) and writes the record that goes to the API as the scope_binding body field: {endpoint_tokens, identity_binding}.
• action/http/collector/collect_http.py, the collector. It reads the manifest and the heads and writes the bundle; its bundle/raw is the files map of the request (raw/HTTP-FACTS.json, raw/COLLECTION-SIDECAR.json and raw/response-heads/<id>.txt).

Both take the same four flags: --fixture-dir (the manifest folder), --out (the producer's output file; the collector's output directory, which must not exist yet), --identity-key-fd (the number of a descriptor the program reads the key from) and --identity-key-id (a label of your choosing for that key, carried in the record as key_id; never the key). The key is 32 random bytes, made for this collection, read once by the producer and again by the collector, so the collector's digests and the producer's binding agree. It must reach each program on a fresh nonblocking pipe holding exactly the 32 bytes and then end of file: a descriptor a shell redirection opens (3<<<"$key", 3< <(printf '%s' "$key")) is a blocking pipe, and the reader refuses it with IDENTITY-KEY-FD-INVALID (a here-string also appends a newline: IDENTITY-KEY-FD-LENGTH). So the key is never an argument, an environment variable or a file; a few lines of standard-library Python open the pipe the way the Action does. From the directory that holds assure-action/ and http-fixture/:

python3.14 -I -B - http-fixture caller-key-001 <<'EOF'
import os, secrets, subprocess, sys
manifest_dir, key_id = sys.argv[1], sys.argv[2]
key = secrets.token_bytes(32)                      # this collection's key: in memory only
def keyed(program, out):
    reader, writer = os.pipe()                     # a fresh pipe per program: the 32 bytes, then end of file
    os.set_blocking(reader, False)
    os.write(writer, key)
    os.close(writer)
    try:
        return subprocess.run([sys.executable, '-I', '-B', program, '--fixture-dir', manifest_dir, '--out', out,
                               '--identity-key-fd', str(reader), '--identity-key-id', key_id],
                              pass_fds=(reader,), env={'PATH': os.defpath}).returncode
    finally:
        os.close(reader)
rc = keyed('assure-action/action/http/action_identity_fixture.py', 'identity-scope.json')
rc = rc or keyed('assure-action/action/http/collector/collect_http.py', 'bundle')
raise SystemExit(rc)
EOF

Exit 0 leaves identity-scope.json (the scope_binding) and bundle/raw (the files). The producer refuses on stderr with a code and exit 3 (MANIFEST-INVALID for a manifest outside the shape above); the collector prints one JSON line with status collection_error and its code, exit 2. The key is dropped when the script ends; the record names it only by its key_id.

Then the request: files from bundle/raw, scope the manifest's ids (the keys of endpoint_tokens), scope_binding the producer's record as written, and send it with the curl above:

python3.14 -I -B - <<'EOF'
import base64, json, pathlib
binding = json.loads(pathlib.Path('identity-scope.json').read_bytes())
files = {str(p.relative_to('bundle')): base64.b64encode(p.read_bytes()).decode('ascii')
         for p in sorted(pathlib.Path('bundle/raw').rglob('*')) if p.is_file()}
body = {'profile': 'http-observed-baseline', 'files': files, 'scope': sorted(binding['endpoint_tokens']),
        'scope_binding': binding}
pathlib.Path('request.json').write_text(json.dumps(body), encoding='utf-8')
EOF

Send the bundle as collected. The collector's sidecar records the digest of every file it wrote, and the checker compares each uploaded file with it: a head or facts file edited after collection, by hand or by a tool that rewrites line endings, is refused ARTEFACT-DIGEST-MISMATCH (a profile_refused, section 9) and charged as one check, because the checker's reader refused it; POST /v1/lint reports the same fault free, so run lint before the paid check. To change what is checked, change the manifest or capture the head again, and run both programs again with a new key: a bundle from one run and a record from another do not agree. POST /v1/lint (section 6) takes the same body, free, and reports the faults found before a check is admitted (the body's shape, the scope fields and the files' readability). On http-observed-baseline its http stage runs the checker's reader, which compares each uploaded head and facts file with the sidecar's digests, so an edited head is an http finding with outcome profile_refused whose text names ARTEFACT-DIGEST-MISMATCH and the file (an edited facts file, FACTS-DIGEST-MISMATCH), and the lint costs nothing: run lint before the paid check. When the http stage ran, the lint record's not_checked list omits sidecar_digests; it sits beside stages_run and stages_skipped (VERDICTS.md section 11).

Requirements and where they came from: requirements, repository, commit

Three optional body fields sit beside profile and files. They are metadata about the check, never a file under raw/.

• requirements: the text of your requirements.md, as one JSON string of UTF-8 text. At most 65536 bytes, 256 lines (a final newline ends the last line) and 8192 bytes per line; beyond any of them the check is refused bad_input with the malformation kind requirements, and nothing runs.
• repository (owner/name) and commit (40 lower-case hex digits) say which repository and commit the check is about. Send both or neither; one without the other is bad_input (kind provenance). A check that carries them appears in the history routes (section 6).
• The API records who sent the pair: provenance: caller for a direct API call, runner when the Action sends GITHUB_REPOSITORY and the pull request head SHA from a valid event file bounded to 16 MiB, otherwise GITHUB_SHA. The pair is checked for shape only. It is never read as access to another account and never as a GitHub attestation.

The requirements text comes from the checked-out workspace, not fetched from the named commit. A pull request workflow may read a merge tree, and pull_request_target may read the base branch, while the metadata names the pull request head. Align the checkout with the commit you intend to check; caller/runner provenance is not a GitHub attestation.

compile_requirements (true or false) may go with requirements: by default a line that does not match one of the profile's statements word for word is read by Claude Haiku 5.5, which proposes the statements it asks for; the server admits a proposal only when its statements and scope exist in the check, and the matcher decides the line. A line Claude Haiku says names one specific route, view or table is not read as a profile-wide statement: it reads not established, with could_not_read, until the profile can bind a statement to that route. A statement about routes or guards is also not read for a line whose own words name one route, a literal path or an operation on a record ("POST /notes/1/delete", "can delete a note", "note deletion"; the rule is in DATA.md), whatever Claude Haiku says. An answer that does not say whether the line names one is not used either. Such a row carries read_as (the statements it was read as), or could_not_read (why it was not), and the verdict carries requirements_compilation with one summary sentence. The reading is drawn from your formalisation line; when that has no balance, nothing is sent and the lines match exactly. false sends no line to the model, and the rows are the exact-match rows. What is sent and kept is in DATA.md.

A check sent without these fields runs as before and has no history. A requirement checked with http-observed-baseline cannot hold today: the HTTP check does not yet carry a verified method and path for each endpoint, so a matched HTTP requirement reads not established with the reason class missing_identity_binding.

The free formalisation quote

A requirement that is not established because no method states it (reason_class missing_method) carries a free quote in formalisation_quote: {line: "formalisation", quote_usd: {low, high}, idempotency_key, quote_fee_usd: 0, calibrated: false, execution_available: false, basis, allowance_remaining, allow_overage_needed}. The quote is shown on every tier, a zero formalisation allowance and an empty top-up included, and is never charged: it runs nothing, holds nothing and writes nothing to your usage. It is an uncalibrated first-draft estimate of the model cost of formalising that one sentence, from the pinned price of anthropic/claude-opus-5.5 (basis names the price table, its date and the token assumption). It is not a price you pay, not a cap and not a promise that a method can be written; the formalisation run itself is a paid later run. Its idempotency_key depends only on the sentence and the profile's domain, never on the repository, the commit or the model. When the price is not recorded, formalisation_quote is null and needs_formalisation_quote stays true. What a paid run sends to the server and to the model, and what is kept, is in DATA.md.

Allowance notices: usage

Every verdict, and GET /v1/usage, carries usage: {month, resets, lines}, where resets is the first day of next month (UTC) and each of lines.report, lines.formalisation and lines.proof_search gives included_usd, used_usd, remaining_usd, percent (the whole percentage used, null when the allowance is 0), threshold (75, 90 or 100 once reached, else null), past_limit and overage_budget_usd. past_limit is metered when the part beyond the allowance is charged at cost x 1.2, and hard_stop when you have set no overage budget or set it to 0: then a request that would go beyond the allowance and your top-up is refused allowance_exhausted, with detail.overage_budget_usd and the quote, until the allowance resets. The budget limits only the part of a charge that your top-up does not cover: a top-up stays spendable under a budget of 0. Overage is off until you set a budget: without one, overage_budget_usd is 0.0 and past_limit is hard_stop. On Premium and Pro, the report, formalisation and proof search lines share one monthly pool, USD 20 or USD 200 of usage a month, at the same rate as overage (cost x 1.2), so each line's included_usd is the pool and its remaining_usd is what is left of it for all three. A line that is a balance granted once, such as the free plan's report balance, adds renews: false, reset: null and debt_usd (what is owed, 0 when nothing is), its remaining_usd is below zero while something is owed, and its past_limit is stop: past the balance, reports stop. Ask Symbolia to set your overage budget, 0 included. On a verdict, each line also says crossed: true when its threshold was reached since the last check, and the job summary then adds one line, for example "Report allowance: 90 % used (USD 4.50 of 5.00); resets 1 Nov; past the limit: metered at cost x 1.2". No e-mail is sent.

Sending again safely: Idempotency-Key

Idempotency-Key is optional. Make one new random value for each check, 16 to 64 characters of A-Z, a-z, 0-9, _ and -, and send the same value again only when you resend that same request, for example after a lost connection.

• The first request with a key creates the check.
• A resend with the same key and the same body and query returns that same check: 200 with the stored verdict, or 202 while it runs. It is not charged again and not counted against your rate limits.
• A resend that arrives while the first request with that key and body is still being read and checked (its sender stopped waiting for the answer) waits for that first request, at most 20 seconds from the resend, instead of being checked again: once the first has created the check, it is answered as above; while the first is still being checked it is server_busy (503) with Retry-After: 20, and is neither charged nor counted against your rate limits. Send it again after that wait (issue #2601).
• The stored verdict comes back with replay: true and first_checked_at, the time in UTC when its first check completed. A check that runs answers replay: false and its own time.
• Only a charged result keeps its key. A failure that was not charged, or one that may pass on a second try (checker_timeout, checker_cpu_limit, checker_error "the check failed unexpectedly", or checker_error with detail.rule restarted), keeps none, so a resend with that key runs the check again, and it is charged when it runs.
• fail_on is applied at render on the stored verdict: a resend that differs only in fail_on is the same check, not charged again, and its answer is decided under the fail_on it sends. A poll, GET /v1/checks/<check_id>?fail_on=..., is decided the same way.
• The same key with a different body, or with a query that differs in more than fail_on, is bad_input with detail.rule idempotency_body_mismatch. The requirements text is part of the body, so a resend with other requirements text is refused this way. The key is bound to the exact bytes of the earlier request body and its query, so whitespace counts: the same JSON written by another serialiser (a client library, then the shell snippet above) is a different request, and the refusal's action says to resend those exact bytes to read the stored verdict, or to send a new key for a new check.
• Keys belong to your account. Another account's key with the same value names a different check.
• The server keeps a key as long as the verdict it points to (30 days).

A malformed key is bad_input. The Assure Action derives its key from the content of the request, so it makes one check per distinct request: a repeat of the same request gets the stored verdict back and is not charged again. It reuses the key on every retry, and with fresh-check: true it sends a random key instead (the Action quick start, section 9).

5. Read the answer

• 200: the check finished. The body is the verdict, schema assure.serve.verdict/v1. See VERDICTS.md. policy.exit is the exit code a CI job should use, and policy.reason says why: nothing_disproven (0, colour green: nothing is disproven within the bounds the first line states), never (0), disproven (1, red: a reading on a machine that was read has a status you fail on; a disproof your fail_on leaves out stays red with exit 0), not_proven (1, red: a prove-class obligation is not proven), unresolved_strict (1, red: under strict, an obligation marked security: true is unresolved), stopped_by_choice (1, red: a reading has a status that is not a verdict and that your fail_on names; the colour says whether anything is disproven), platform_owned (0, red: every disproof your fail_on names is platform-owned) or could_not_look (3, yellow: the input-integrity gate stopped the check, no machine was read, or no selected unit was observed). A fails reading whose findings are all platform-owned keeps the colour red with exit 0 and policy.reason platform_owned: the disproof is someone else's to fix. Refused machines, unobserved endpoints and a run with no verdict are named and do not change the exit. With fail-on: fails, at least one machine read, a clear input-integrity gate and no red findings, a partly observed scope with zero usable readings is still green, exit 0, policy.reason nothing_disproven: green says nothing was disproven, not that anything was read. Read completion.usable_readings before trusting green: when its count is 0 and coverage_complete is false, no obligation was established and the first line names what to collect. machines lists the machines read and those that could not be read, with the checker's reason. rows and counts keep the checker's raw statuses. A row the checker kept on a machine it refused is coverage: every rendered surface (the first line, the summary, the annotations, the not-established list, the report) reads it as not observed. not_established lists each obligation that could not be established with its reason_class, owner, what it needs and action; undecided_by_cause groups that list by reason_class, leaving out empty domains, largest first, one {class, rows, action, owner, ids} per class with the action that decides those rows, and is absent when no entries remain after empty domains are left out (VERDICTS.md section 9); completion answers whether the readings are usable, the coverage complete and the policy passed; observed_facts holds, for each observed HTTP endpoint, the facts its readings used (headers and cookie attributes, no cookie value or redirect URL); bounds and bias give the rest of the first line; warnings is a list of {kind, text, ...} entries, [] only when nothing applies: read kind first, because new kinds can be added later. The kinds today are endpoint_non_success (on http-observed-baseline: one per endpoint that answered 4xx or 5xx, with the checks it hid), known_limit (on postgresql-observed-baseline: one per served RLS-1-OB row of any status, so a Postgres run with nothing wrong can still carry one) and declared_ignored (on postgresql-observed-baseline: one per key of the declaration file the check dropped) and dynamic_registration (on python-auth-declared-model: one per registration site whose guards were not read, with a path and line when its module names exactly one repository file); see warnings in VERDICTS.md section 1 for each kind's fields. VERDICTS.md section 9 gives the first line word for word. When you sent requirements, the verdict carries requirements, one row per requirement with its state (holds, not_established or disproven), its reason_class, its establishing_action and its formalisation_quote (VERDICTS.md section 10).
• 202: the check is still running 20 seconds after the API received the request (its upload and admission count in those 20 seconds; when they take longer than 19.5 seconds, the check is given half a second after its admission before the 202). The body is {"check_id": "…", "status": "running"}. Poll for it:

curl -sS https://api.symbolia.ai/v1/checks/<check_id> \
  -H "Authorization: Bearer $ASSURE_API_KEY"

Poll every few seconds. A running check answers 202 again. A finished check answers 200 with the verdict.

• Any other code: a typed outcome (section 9). The body is schema assure.serve.failure/v1 with outcome, reason and action. Current answers also state charged; historical stored answers can lack it (section 9). A refusal answered before a check was admitted, whatever its status, has check_id: null and a top-level request_id, the same 16 hexadecimal characters as the X-Request-Id response header and as the request_id of our log line for that request: quote it as the citation for an answer that has no check id. A typed failure of a check that was admitted is the stored result: it has its check_id and no request_id, when it is first answered and when it is read back from GET /v1/checks/<check_id>; cite its check_id.

The verdict stays readable at GET /v1/checks/<check_id> for 30 days. Only your account can read it.

On the free plan, the verdict can also carry upgrade, {"url": "…", "line": "…"}: a Premium checkout link filled in with your account, and one sentence that ends with it. When your free balance is spent, it also carries notice, one sentence that says so, and the Action prints it at the start of the upgrade line. A paid plan's verdict does not carry it, except a gifted plan in its last 30 days: then notice names the day it ends (for example "Your gifted Premium plan ends on 2027-04-14.") and line is "To keep it, upgrade at" followed by the url. It changes no other field. The check answer OpenAPI contract describes it.

6. Other routes

An agent can call these routes as tools over MCP: MCP.md gives the install line for Claude Code, the configuration for Codex and Cursor, the five tools, and what leaves your machine.

7. Limits

The request-body limit applies after base64 and JSON encoding. A repository below 8 MiB of decoded source can still exceed that encoded limit.

Base64 makes a file about a third larger, so the 8 MiB body holds about 6 MiB of files.

The minute limit counts every POST (checks, lint, quote, feedback, report and formalisation requests). The day limit counts records: one for each file in a check submission, and one for each report or formalisation request. Reads (GET) are not counted. Credit is checked when a check is admitted, after the size, name and limit checks.

The window each POST route counts in, the rate_window of its GET /v1/profiles routes row (minute+day: the minute limit and one day record; minute: the minute limit only; none: neither). GET routes are none.

A request over a limit is refused before the checker runs and is not charged. rate_limited answers carry a Retry-After header in seconds, and so does server_busy when the check queue is full (the server's check time limit, 60 s: by then a running check has ended) and when the first request with the same Idempotency-Key is still being checked (20 s, section 4). A check submission refused server_busy after its files were read (the check queue is full, or its Idempotency-Key could not be recorded) keeps only its first day record, so that retry does not spend the bundle's records again (issue #2451).

8. Metering

• Input tokens are the decoded file bytes divided by 4, rounded up.
• The price is USD 0.10 per million input tokens.
• Each account starts with USD 5.00 of credit. The credit cannot be topped up. The credit bounds the checks of a free account only: an account on a paid or internal plan is not refused credit_exhausted, and its checks are still metered.
• For a newly run API check, the envelope's charged records the server's decision (section 9). After the checker has started, checker_error, checker_timeout, checker_cpu_limit and checker_memory_limit are charged unless the answer states an explicit no-charge decision. A refusal before admission, the checker's own internal error, a malformed bundle refused by the free pipeline for python-auth-declared-model, and a check the server could not start or finish on its own side, such as one cut short by a server restart, are not charged. Local runs charge nothing; a stored readback or an idempotent replay makes no new charge. A historical answer without the field leaves its original charge unknown.
• When the usage ledger cannot record charges, the server runs no check: it answers server_busy until the ledger works again.

Example: 1 MiB of files is 262,144 tokens, which costs about USD 0.026. USD 5.00 covers about 190 such checks.

9. Typed outcomes

Current API verdict and failure answers state charged beside outcome: it records whether the server counted this as a charged check, not money spent or a new charge for reading the answer. A valid free-profile check can carry charged: true with zero monetary cost. A stored answer or an idempotent replay keeps the original field; neither request charges again. Historical stored answers can lack the field: treat the charge as unknown, not false. Local verdicts and failures say charged: false; an Action failure can say null when a sent check's charge could not be read (VERDICTS.md section 1).

The Charged column describes a newly run API check. A refusal before admission, the checker's own internal error, a check cut short by a server restart, and a malformed python-auth-declared-model bundle refused by its free pipeline are not charged. depends means the outcome alone does not decide it: read the envelope's charged. For bad_input, oversize_input and collector_refused, depends is the checker's start: nothing is charged before the checker starts; once a checker starts, the answer's charged field states the decision, and a refusal whose detail.charge is false stays uncharged even then. A lint finding (section 6) carries severity (refusal or notice) and a predicted charged; lint itself runs no check and charges nothing.

A refusal answered before a check was admitted carries request_id beside check_id: null: cite it as the request's identity, as section 5 says. A typed failure of an admitted check has its check_id and no request_id. Every failure body the API sends has detail.served_from (issue #1665): handler when it was minted while answering this request (a refusal before admission, an unreadable stored record, or a check that ended without a result), store when it is the admitted check's stored failure, both when it is first answered and when GET /v1/checks/<check_id> reads it back (VERDICTS.md section 7); a failure stored before the key existed is replayed as stored, without it.

HTTP derive codes. A profile_refused reason of the http-observed-baseline profile reads derive_observed refused (input_fault): <CODE>: <file>; detail.cause_code is the code and detail.path the file. The file is one of the three kinds you sent (raw/HTTP-FACTS.json, raw/COLLECTION-SIDECAR.json or a response head under raw/response-heads/); the three codes named in the row above carry no file. The table lists every code the derive raises against the files you upload (a code outside it is the checker's own fault and is checker_error, not charged). None of these faults is fixed by editing a file: the sidecar records each file's digest, so an edited file is refused ARTEFACT-DIGEST-MISMATCH. Run the identity producer and collect_http.py again with one key, and send that run's files and scope_binding together.

The Assure Action has three outcomes of its own, which the API never sends: collector_cannot_connect (the collector could not reach your database), api_unreachable (the runner could not reach the API: three attempts, and on the check's send or the poll of a sent check further retries with backoff while the API stays unavailable, up to 300 s of waits) and api_error (the API's answer was not one the Action accepts; a 5xx without a failure envelope on those two requests is retried the same way). Each exits 3. The Action also gives collector_refused when the collector itself refuses the collection (for example a collection role with too broad a grant).

The front proxy enforces the 8 MiB body cap too. An oversize request may get a plain 413 with no JSON body.

10. Your data

Your files are written to a scratch folder for one check, and the folder is deleted when the check ends. On the Premium tier a sealed copy is kept for the formal shadow (see DATA.md). The verdict is kept 30 days. Details are in DATA.md. What a verdict claims is in SCOPE.md.

11. Formal shadow (local draft, off by default)

This section describes an opt-in local draft pending independent review. It makes no production availability or physical validation claim. Premium (USD 20/month) maintains the authentication shadow with medium reasoning. Pro (USD 200/month) names authentication plus the essential state machine with high reasoning. The state-machine and Enterprise codebase stages are not live; their requirement rows remain not_established, with the stage and required tier disclosed.

The deterministic check returns immediately. A paid response can also carry shadow, and GET /v1/checks/{id}/shadow serves the separate result on the same check id. A current shadow means the change touched no read-set dependency or input digest: no model call and no charge. A relevant change makes the shadow stale; the quote is visible before admission, and the separate result reads yellow (not_established, remodelling) until verification. A failed remodel preserves the dated last_verified reading and reports remodel_failed:<reason>.

The authenticated draft quote route is POST /v1/checks/{id}/shadow/quote. Send {} or {"verifying_stage":"authentication"} to request the free quote. Quoting starts no paid work. To accept, send {"accept":true,"quote_id":"<the exact returned quote_id>"}; add "allow_overage":true only when intended. Acceptance is a draft proposal that remains pending verification. The local draft makes no actual paid model calls.

Quoted allowance and pool amounts use the charged amount: raw model cost times 1.2. Keep raw model cost separate from the amount reserved against the pool or charged to the account. A replay must not reserve or charge twice. Neither a quote nor an accepted proposal establishes a requirement.

Operators keep the draft off with make_server(..., shadow_enabled=False), the default. The authenticated shadow routes exist only when the server is explicitly constructed with shadow_enabled=True. There is no production-enabling CLI switch. The trusted runner supplies read sets, snapshots, stage proposals and verified model records; these are never accepted as client JSON assertions.

Existing verdict and shadow sidecar retention remains 30 days. A hashed commit tombstone survives until account-state deletion, preventing another charge after its check expires; an expired owner cannot be remodelled again by this draft. Restart cancels an unstarted fixture job without a call or charge. Maintained-model retention beyond 30 days and retry attempts remain open before the paid product can be released.

12. The free check summary: GET /v1/checks/{id}/summary

GET /v1/checks/{id}/summary (section 6) is served on every plan, authenticated with the same key as the check. It reads the stored result and makes no model call, reservation or charge. The original GET /v1/checks/{id} remains the full record.

Start with coverage_line and requirements_count, then read headline and policy. The headline names one finding; when more than one obligation is disproven it reads "disproven: k, first <obligation> — …", and disproven lists those k as {id, machine, status, witness, platform_owned, requirement} in the same order (witness is null when the reading carries none; requirement is null unless the disproof comes from a requirements.md row none of whose obligations is already listed, and then id is that requirement's id), so read the whole list before repairing: fixing the first alone leaves the others. A row with platform_owned true is a Supabase- or extension-owned object, someone else's to fix; those come after your own. counts is the stored status count of the obligation rows (fails, holds, …), as on the full record; a fails row kept on a refused machine is counted there but is not in disproven. For example, a sparse input can say "Usable readings: 0 of 40" while its colour is green and policy.exit is 0: nothing was disproven, but no usable reading was made. The summary keeps those results as given. Each compact requirement row retains its state, reason and original establishing_action, with a next_step for the customer. A row's reason is the same string as the full record's row; when the record has no reason words, it is the matched reading's witness words (as the first line gives them), else the reason class's text; a row with truly no words carries null, never an empty string.

When the headline says a machine was refused, machines_refused says which and what admits it, so you need not fetch the full record for that: beside count and by_status it carries machines, one entry per refused machine, {machine, status, reason, needs}, copied from the full record's machine_refusal rows in their order, then from the record's machines.refused for a refused machine that has no row of its own (the observed profile reports refusals through its readings and writes none). count and by_status are counted over the record's machines.refused when every entry there carries a status, so they agree with the list even for a verdict stored before the record counted it that way (issue #411). The summary also carries the record's machines block (read, refused with each machine's reason and status, total, source) beside it. reason is the checker's text as written; needs is {kind, key, action} (kind is declaration, input or method, action one sentence saying what to collect or declare, or for a pg_hba.conf the sidecar records as missing or unreadable the two statements GRANT SELECT ON pg_catalog.pg_hba_file_rules TO <role>; GRANT EXECUTE ON FUNCTION pg_catalog.pg_hba_file_rules() TO <role> (PostgreSQL refuses the view's read with the SELECT grant alone), <role> the collection role read from the readings and quoted as SQL writes it, or the words the collection role when no collection role is read (the readings' own grant text is used instead when it names both statements); status unsupported keeps needs null), or null when what admits that reason is not tabled yet. A refused machine's obligations are not readings and are not in requirements or the full record's not_established; the needs.action is their next step. A verdict stored before refusals were recorded has machines_refused null.

When a missing-method requirement has a quote with execution_available: false, its next step says that formalisation execution is unavailable and points to POST /v1/feedback for a deliberate coverage request. The estimate is not an executable offer. To log that gap, send {"kind":"coverage_gap","text":"Describe the requirement and the missing method.","check_id":"<check id>"}. Feedback is free, changes no verdict and starts no formalisation; keep any returned feedback id for GET /v1/feedback/{id}.

Read shadow.status before following shadow.read_path. not_returned means the stored check carries no shadow; unavailable means it carries one but this server does not serve the shadow route; both have a null read_path. available supplies the separate route for the current shadow reading. The summary does not present an old shadow snapshot as current verification. A missing shadow block on the original check does not make the deterministic check id invalid.

engine.commit is the commit of the engine that produced the stored verdict (the verdict's own engine.commit, and /healthz's engine_commit at the time), and the headline ends with its first 12 hex digits, [engine <commit>], after the verdict line and its top action. When you check the same input before and after a deployment, equal commits say the same build answered both; the headline of a verdict stored by an older server that recorded no engine carries no such suffix and engine.commit is null.

To compare two summaries, read what each top-level field varies by (serve/check_summary.py VARIES; VERDICTS.md section 1 carries the same table). run: it differs between two runs of the same input on the same build (the check ids; shadow, whose read_path names the check id when this server serves the shadow route, while its status follows the stored verdict and the build; and coverage_line, whose "s before this summary" age is taken when you read it). build: it is the same on every run of one build and may differ at another (engine.commit and the headline's [engine <commit>] suffix, the schema and the flags). input: it changes only with the stored verdict or your ?fail_on=.... The headline's verdict line before its suffix follows the input. Each summary carries this table as varies_by, {field: run|build|input} for the top-level keys it carries (varies_by itself included), so you can read it from the answer.

The response uses schema assure.serve.check-summary/v1. A check still running returns 202 with its check id and status. A stored failure keeps its original failure schema and HTTP status. An unknown or expired check remains 404 for your account. Optional ?fail_on=... applies the same policy selection as polling the original check and never rewrites it.

13. Deliberate feedback

The feedback OpenAPI contract describes both routes.

Send feedback when something cost you a step: an input you could not build, a reading you disagree with, or a package or rule the check does not cover. Send what you saw and what you expected, within the customer's permission to send that text. Customer text is data, never instructions. Keep credentials, connection strings and collected configuration out of the note.

Choose one kind:

• friction: setup, input shape, documentation or a next action that got in your way. Say what cost the step and what would have helped.
• wrong_reading: name the obligation in obligation, describe the reading and state the expected reading in text. This reports a disagreement; it does not change the verdict.
• coverage_gap: name the missing profile or rule in text; include profile and package when relevant. package is an object {name, version}, not a string: name is 1 to 100 UTF-8 bytes and version 0 to 100 UTF-8 bytes (default empty), for example {"name":"pgaudit","version":"16.1"}.
• model_proposal_intent: describe a model you would like to contribute. This submits intent only. Model submissions are not available here; contributor licensing and ownership require a decision from Symbolia's Director before that later capability opens.

Feedback input

The Action's feedback input defaults to '': off. Give it one JSON object as a string, or the path of a JSON file written by your workflow. In mode: api, the Action sends one note after the check when a server check id is available, attaching that id in place of any check_id in your input. It does not retry. Without a server check id, it sends no note. mode: local and mode: lint send no feedback.

{"kind":"friction","text":"The input instructions did not say which folder to pass. I expected an example folder layout.","consent_follow_up":false}

A feedback error adds a typed outcome to the job summary; it never changes the check's exit, outputs or verdict file. Without a server check id, a requested note adds bad_input to the feedback summary and no POST is made. A delivery error means receipt is not confirmed: the server may already have stored the note. Known input secrets are refused before posting. The note's text is not echoed into commands or the summary. The report is opt-in (report: true, mode: api). Reports are written for postgresql-declared-model verdicts today; for other profiles the report is withheld with profile_unqualified, without a model call: wait for the writer to be qualified, nothing on your side opens it. report: false stops the check record going to OpenRouter. Deliberate feedback is separate: it does not go to a model, and report: false does not turn it off.

Feedback API

POST /v1/feedback accepts one UTF-8 JSON object, with no duplicate keys, non-finite numbers or extra keys. Authenticate with the same API key as checks, in the Authorization: Bearer header. Send Content-Type: application/json and one Content-Length; no transfer encoding or query parameters.

Every field in one body, as the route accepts it:

{"kind":"coverage_gap","text":"No rule reads the pgaudit settings. I expected a reading of pgaudit.log.","check_id":"0123456789abcdef0123456789abcdef","profile":"postgresql-declared-model","profile_wanted":"postgresql-pgaudit","obligation":null,"package":{"name":"pgaudit","version":"16.1"},"agent":{"model_id":"example-model-1","client":"example-agent/1.0"},"consent_follow_up":false}

A refusal of the body's fields (an unknown key, a missing kind or text, a wrong type or form) is bad_input (400) whose detail.accepted_fields lists the nine keys above, sorted, and whose detail.kinds lists the four kinds, so one refusal names the whole accepted shape. detail.shapes gives each key's form: package is {name, version}, agent is {model_id, client}, kind lists the four kinds, consent_follow_up is boolean and every other key is text; detail.example is one minimal valid body, the friction example this section prints. The reason for an unknown key names that key; no value is ever echoed. A refusal of one named field also carries detail.malformation.pointer, that field's JSON pointer (such as /check_id); a body that is not one JSON object carries none. A value or key that carries an Assure API key (asr_, an 8-hex key id, _ and a 43-character secret) is refused bad_input and nothing is stored: a value's refusal names its field, and such a key is never named. A body that is not UTF-8, is not JSON or repeats a key is refused before its fields are read: bad_input (400) with detail.malformation.kind body_not_utf8 or body_not_json, and without accepted_fields, kinds, shapes or example.

The request body limit is 16,384 bytes. Feedback is free on every plan, with no charge or usage ledger row. Each POST uses the same per-account minute rate window as checks; a repeat still uses that window. Up to 100 new notes per account per UTC day are accepted. Within one account and UTC day, the same kind, check id and exact text returns the first note with duplicate set to true, without a new row or another daily slot. Changing other metadata alone does not change that identity. A rate refusal is rate_limited (429) with Retry-After; a daily refusal names window set to day and the wait until midnight UTC.

POST returns 200 with schema, id, received_at, kind, check_id, profile, obligation, package, sha256, duplicate, related, routed and the response flags; it does not echo the text. check_id, profile and obligation are the stored row's values (null when not sent) and sha256 is the stored row's deduplication SHA-256, the hash of kind|check_id|text rather than of the text alone, so a record can cite the note without trusting its own request body; on a duplicate they are the first row's. related lists this account's other notes of the same kind and profile whose status is not merged or declined, among its notes of the newest 7 UTC-day files, newest first and at most 10, each as id, kind, profile, status and match (kind+profile), so a second note on one gap can see the first; when the note has no profile it lists the open notes of the same kind of any profile, null included, each with match kind. routed says where the note goes next: digest, the daily agent feedback digest that reads it (Agent feedback digest YYYY-MM-DD, the note's UTC day), status_route, the GET /v1/feedback/{id} route that answers its state, and next, one sentence naming both. GET /v1/feedback/{id} returns 200 with the stored row, including text, the account and key ids, timestamp, metadata, the deduplication SHA-256, check_known, rows_unreadable and response flags. check_known records whether that account held a verdict for the supplied check id at submission time; it is not a live lookup. rows_unreadable counts unreadable lines in that note's UTC-day file, including zero. status is the note's state as Symbolia acts on it: received until then, in_pr with the pull request number pr, merged with release, the engine commit that ships the change, or declined with a reason; updated_at is when it was set. When the state cannot be read just now it reads unavailable with a reason, and the note still answers. A malformed, absent or another account's id returns the same not_found (404). Neither route accepts query parameters.

Internal only (Symbolia accounts on the internal tier; every other tier reads not_found): GET /v1/feedback/digest?since=<ISO 8601 timestamp with zone> answers the notes of every account from since as JSON, built by the daily digest's own readers: counts by kind and state, coverage_gaps grouped by the profile they name and ranked by distinct accounts, and notes newest first, each with id, account, kind, profile, status, check_known, text cut to 500 characters and received_at, and never a key, a key id or a hash; POST /v1/feedback/{id}/status with {"state": ..., "pr": ...} (and release or reason as the state takes them) sets the note's state with the same rules as the operator command, so the note's own account reads it on GET /v1/feedback/{id}. Both are free, change no verdict and no ledger row, and every read and every change appends one row (time, actor account, key id, route, note ids) to an append-only operator log under the server's state directory.

Notes are kept for 12 months, with retention and removal on request handled by the operator. The daily digest reads notes without changing them: counts by kind, counts by profile wanted with distinct account counts, packages by kind with distinct account counts, bounded text from every kind for triage regardless of consent, notes consenting to follow-up, and friction notes by check id. Consent controls follow-up only; it does not hide a submitted note from triage. Account ids appear as stable short hashes. Customer text appears only in fenced data blocks marked DATA>, with control and format characters removed and display length bounded. The digest reports skipped or unreadable files and unreadable rows, including zero. When the feedback collection cannot be accessed, the digest stops with an error instead of reporting an empty day. Feedback is not read by the checker or report writer. No automatic demand-ledger entry or model proposal is created.

14. Paying for a plan

Upgrade to Premium (USD 20 a month)

Accounts start on the free plan. Premium (usd_20, USD 20 a month) adds checks of your app's sign-in and session routes, not only the database; paid formalisation of requirements no method states yet; and one monthly pool of USD 20 of usage that reports, formalisation and proof search share.

To pay, open the Premium Payment Link with your account id appended as client_reference_id, as the upgrade line at the top of a free account's job summary does: https://buy.stripe.com/<link>?client_reference_id=<your account id>. You can read your exact link before your first run: on the free plan, GET /v1/usage carries upgrade, {"url": "…", "line": "…"}, the same link and sentence a free account's verdict carries. When the payment completes, your account moves to Premium; no other step is needed. A paid plan's answer never carries upgrade, and while Symbolia has set no Payment Link no answer does: then ask Symbolia for a checkout link, or ask for one with POST /v1/billing/checkout (below).

Checkout by API

An agent asks for a checkout link; its human pays. Accounts start on the free plan. To move to Premium (usd_20, USD 20 a month) or Pro (usd_200, USD 200 a month), send:

POST /v1/billing/checkout
Authorization: Bearer asr_...
Content-Type: application/json

{"tier": "usd_20"}

The answer is {"schema": "assure.serve.billing-checkout/v1", "url": "https://checkout.stripe.com/...", "session_id": "cs_...", "tier": "usd_20", "account_id": "..."}. The agent hands the url to its human. What the human sees is Stripe's hosted checkout page for that plan: the price, a card form, and Stripe's own terms; nothing of yours is shown there but the plan name. Nothing changes until the payment completes: Stripe then tells this server over its signed webhook, the account's plan moves, and the next request that needs a paid plan (the paid formalisation routes, refused tier_required on the free plan) is admitted. A link that is never paid changes nothing. Cancelling the subscription in Stripe returns the account to the free plan at the next webhook.

Symbolia may also send you a Premium Payment Link: https://buy.stripe.com/<link>?client_reference_id=gh-<your-github-org>. It opens the same Stripe page for Premium (usd_20), and the client_reference_id names your account, so no API call is needed: when the payment completes, the account gh-<your-github-org> moves to Premium through the same webhook. Open the link exactly as you received it; a link without that part, or one naming an account Symbolia has not issued, moves no plan, and Symbolia matches the payment to you by hand or refunds it.

Overage beyond a plan's allowance is sent to Stripe once a month as one metered usage record per account, as the usage lines of GET /v1/usage show it. What Stripe receives is in DATA.md.

15. python-auth-declared-model: a Python repository, checked in process and free

A Python (Flask, FastAPI, Django or standard-library http.server) repository checked against AUTH-CATALOGUE-001 under your declaration, in process and free. Send raw/REPOSITORY.json (the file list with each file's bytes, sha256 and git mode, the commit and the tree id, and the seven flags at their standing values), raw/declaration.json (schema assure.python-auth.declaration/v1, a copy of repository/declaration.json; the served check reads raw/declaration.json, and a copy whose bytes differ is refused input_pin_differs (declaration_bytes) naming both files and their sha256; for FastAPI, Django or standard-library http.server, schema assure.identity.declaration/v1 with stack python/fastapi, python/django or python/stdlib-http, and raw/REPOSITORY.json also carries declaration_sha256, the sha256 of raw/declaration.json (a digest that differs is refused input_pin_differs (declaration_sha256)); a stack other than python/flask, python/fastapi, python/django or python/stdlib-http is refused profile_refused), and every repository file as raw/repository/<path>, requirements.md included. At most 2000 Python files, within 2048 files per request and 512 KiB per repository file; the encoded request body is at most 8 MiB. No server is contacted and no model runs.

A structural refusal names its class and source location, for example unregistered_blueprint at app/__init__.py:21, followed by a next step and the checker's original reason. If several submitted files match a source name, the action retains that module or source name. A bound refusal asks for input within the named bound; other input refusals ask you to review the repository or declaration. This profile has no collection step.

What to send: POST /v1/checks with profile python-auth-declared-model and these files, nothing else beside them:

The bound is the one GET /v1/profiles publishes: at most 2048 files in a request and 512 KiB per repository file; more is oversize_input (413). The encoded request body is limited to 8 MiB, including base64 and JSON overhead. The checker separately accepts at most 2000 Python files; exceeding that ingest bound is a representation refusal. When collecting an artefacts directory or a local directory, the Action and local mode leave a repository file over 512 KiB out of the bundle. The Python checkout path instead stops with oversize_input (exit 2) for a repository source file over that cap; it does not drop that file or print an ignored notice. If a supplied raw/REPOSITORY.json still lists that file, the check returns profile_refused (input_pin_differs: file_absent, exit 3, not charged); no verdict comes back and the ignored notice is not printed. For an artefacts directory with no manifest supplied in mode: api, the generated manifest lists only the retained files, so the checked repository excludes the dropped file; the remaining repository and declaration decide the outcome and exit under normal charge policy, and a returned verdict prints "NAME: over CAP bytes (optional input)". A name outside the three forms, or a missing raw/REPOSITORY.json or raw/declaration.json, is bad_input (400) before anything runs. A bundle the checker cannot read (a declaration that breaks its schema, a file list that does not match the files, a symbolic link) is profile_refused (422), its reason names the rule and the file, its action says what to correct, and nothing is charged. A declaration the checker refuses (declaration_invalid, with /stack among its faults, first or later) whose stack is registered but has no runner leg on this build is instead profile_refused with detail.malformation.kind stack_not_wired, field stack, its expected naming the missing leg (DECLARATIONS.md); a stack that is no registered stack stays declaration_invalid. POST /v1/lint also gives stack_not_wired for a registered stack without a runner leg, naming the same missing leg without admitting a check. A declaration still refused as declaration_invalid also lists every fault, up to 50, in detail.faults as {pointer, keyword, text}, the first being the one the reason names.

One manifest, as the checker's own fixture flask-session-a sends it (five files; commit and tree are that fixture's; the seven flags are at their standing values and every one is required):

{
  "schema": "assure.codeauth.repository/v1",
  "commit": "c4599586ad45c2029dfc820678178a82efbe6562",
  "tree": "bdf4ccd32c2d6866aea6734ca02cc062b0e5dac9",
  "files": [
    {
      "path": "app/__init__.py",
      "bytes": 1750,
      "sha256": "1c43adc9bba43e0490ee48cc512e6bea4d48a862d63c2b4fa01cd1ea0e4b2e0c",
      "mode": "100644"
    },
    {
      "path": "app/guards.py",
      "bytes": 515,
      "sha256": "a2b2ed0867dde86b6f8ae169e5d4873613abd84007d70b632d33a8e9a9370e9e",
      "mode": "100644"
    },
    {
      "path": "app/store.py",
      "bytes": 264,
      "sha256": "3b97abc456961e5085d7de4def70ca788a2919252a6f46fea09378e182f4e155",
      "mode": "100644"
    },
    {
      "path": "declaration.json",
      "bytes": 1456,
      "sha256": "2b04b01b7038d87d8f39c0f54c035e224730412639f0c074c2f1a5ed53db67c1",
      "mode": "100644"
    },
    {
      "path": "requirements.md",
      "bytes": 180,
      "sha256": "19fce38cbb2ae7d3e38b5a4ea5be80ffd9b4a08c2ce8023ac47d4090f6435292",
      "mode": "100644"
    }
  ],
  "execution_authorized": false,
  "hardware_authorized": false,
  "industrial_release_authorized": false,
  "release_allowed": false,
  "physical_validation": false,
  "simulation": true,
  "self_approved": false
}

Writing the bundle: raw/REPOSITORY.json carries the commit and the git tree id of the files sent, so write it with git rather than by hand. From the repository at the commit you are sending, with every file committed and no uncommitted change, this recipe copies the tracked files to raw/repository/<path>, copies the declaration beside them and writes the manifest: commit from git rev-parse HEAD, tree from git rev-parse 'HEAD^{tree}', one row per file from git ls-files -s (its mode) with wc -c and sha256sum, and the seven flag keys the schema requires (execution_authorized, hardware_authorized, industrial_release_authorized, release_allowed, physical_validation, simulation, self_approved, with the values shown; a manifest without them is profile_refused). It refuses a symbolic link or a submodule, which the checker would refuse. It sends the whole tree: a partial send must list exactly the files sent and compute tree over that subset (the git tree id of those files alone), which HEAD^{tree} is not. Keep within the bound: at most 2048 files in the request (the two raw/ files included) and 512 KiB per file, with at most 2000 Python files and an 8 MiB encoded request body.

cd repository      # the git work tree, at the commit you are sending, with no uncommitted change
if git ls-files -s | grep -q '^1[26]0000 '; then
  echo 'a symbolic link or a submodule is tracked; the checker refuses it' >&2; exit 1
fi
rm -rf ../bundle && mkdir -p ../bundle/raw/repository
git ls-files -s | while read -r mode blob stage path; do
  mkdir -p "../bundle/raw/repository/$(dirname "$path")"
  cp "$path" "../bundle/raw/repository/$path"
done
cp declaration.json ../bundle/raw/declaration.json
{
  printf '{"schema":"assure.codeauth.repository/v1","commit":"%s","tree":"%s","files":[' \
    "$(git rev-parse HEAD)" "$(git rev-parse 'HEAD^{tree}')"
  sep=''
  git ls-files -s | while read -r mode blob stage path; do
    printf '%s{"path":"%s","bytes":%s,"sha256":"%s","mode":"%s"}' "$sep" "$path" \
      "$(wc -c < "$path" | tr -d ' ')" "$(sha256sum "$path" | cut -c1-64)" "$mode"
    sep=','
  done
  printf '],"execution_authorized":false,"hardware_authorized":false,"industrial_release_authorized":false,'
  printf '"release_allowed":false,"physical_validation":false,"simulation":true,"self_approved":false}\n'
} > ../bundle/raw/REPOSITORY.json
cd ..

Then the request, from the bundle:

cd bundle          # written above: raw/REPOSITORY.json, raw/declaration.json and raw/repository/...
{
  printf '{"profile":"python-auth-declared-model","files":{'
  sep=''
  find raw -type f | LC_ALL=C sort | while IFS= read -r name; do
    printf '%s"%s":"%s"' "$sep" "$name" "$(base64 < "$name" | tr -d '\n')"
    sep=','
  done
  printf '}}'
} > ../request.json
cd ..

curl -sS https://api.symbolia.ai/v1/checks \
  -H "Authorization: Bearer $ASSURE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  --data-binary @request.json \
  -o response.json -w '%{http_code}\n'

What comes back: the same verdict envelope as every other profile (section 5), with one machine, M1. rows carries one reading per catalogue obligation (AUTH-1 to AUTH-6): holds, fails (the obligation is disproven, with its witnesses and locators under readings.M1), missing_method (no method states it; the free formalisation quote applies when a requirements sentence matches), not_evaluated or representation (the repository's shape is outside what the checker reads, with its reason). policy.exit is 1 when a reading fails, 3 (policy.reason could_not_look, section 5) when the machine could not be read (representation: M1 is under machines.refused with the checker's reason, and the outcome is no_verdict), 0 otherwise, under the same fail_on words as the other profiles. The check is free: it holds nothing, charges no line and writes nothing to your usage beyond the minute window every check counts in. It reaches no model and no paid runner.

The method forms: method_forms

The python-auth-declared-model row of GET /v1/profiles lists method_forms, one entry per method form the checker's grammar admits (FORMS in the checker's methods.py). lean_decidable is true when lean_emit can decide a formula of the form as a Lean theorem, and lean_decidable_when says which ones: a route_requires formula is decided only when each of its atoms is of a kind in atom_kinds and each actor_role atom names a role in actor_roles (none, admin, user, the template's Role type). Any other formula, a catalogue one, one with a premise atom or one guarded by another declared role, is still read in S4a and is refused in S4b as a formula_not_emittable theorem row; lean_decidable_when is null for a form lean_emit decides no formula of. consumers lists the modules that read a formula's form: the checker's methods.py and lean_emit.py, each runner module that calls a function of theirs that reads it, and each module that reaches those through run_paid. runner/tools/codeauth/run.py (run_paid) and runner/tools/codeauth/maintain.py (through run_paid) reach the paid seat.