Decision audit logs

Turning it on

If a request does not include the header, the server checks only the header and does not look up the key.

What a receipt holds

A query against a given corpus_version returns the same data every time because the corpus is content-addressed. The envelope hash still differs between two identical queries because every response carries its own request_id. This makes the hash a receipt that proves which exact bytes one caller received.

Checking a receipt

Hash your response bytes with SHA-256 and compare the result to envelope_sha256. Include the trailing newline, which curl passes through by default.

$ curl -s -H "Authorization: Bearer pit_live_..." -H 'X-PIT-Audit: on' \
    'https://api.pit.aqx.llc/v1/news?ticker=SIVB&as_of=2023-03-10T23:59:59Z&limit=2' \
    | shasum -a 256

The resulting hex string matches envelope_sha256 in the receipt. Refused calls are also logged. For example, a 409 response for a coverage hole produces a receipt with a null corpus_version because no corpus answered the request.

Reproducing params_digest

To calculate params_digest: parse the query string, sort each parameter's values, sort the parameters by name, and re-encode them as percent-encoded k=v pairs joined by &. Then compute the SHA-256 hash of that string. If a request has no query string, hash the empty string.

import hashlib, urllib.parse

def params_digest(query):
    pairs = urllib.parse.parse_qs(query, keep_blank_values=True)
    canon = urllib.parse.urlencode(
        sorted((k, v) for k, vs in pairs.items() for v in sorted(vs)))
    return hashlib.sha256(canon.encode()).hexdigest()

params_digest("ticker=SIVB&as_of=2023-03-10T23:59:59Z&limit=2") is 701c3eae4f1dbcfaf5147f12dc07d0526f40680265498eb1ef170d0770317851.

Reading your log

$ curl -s -H "Authorization: Bearer pit_live_..." \
    'https://api.pit.aqx.llc/v1/audit-log?day=2026-08-27&limit=100'

The response uses the standard envelope with one receipt per item in results. Receipts are scoped to your account.

Pages are ordered chronologically by ts. The log is append-only, so existing pages never change. When you resume pagination, you receive only newer entries.

Exporting

Use format=jsonl to receive raw application/x-ndjson with one receipt per line and no outer envelope. If more pages exist, the next token is in the X-PIT-Audit-Next-Cursor response header.

$ curl -s -H "Authorization: Bearer pit_live_..." \
    'https://api.pit.aqx.llc/v1/audit-log?format=jsonl&day=2026-08-27&limit=1000' \
    > receipts-2026-08-27.jsonl

Knowing the log is complete

Receipts are written asynchronously after each response using a fixed-depth queue. If the queue is full, the server drops the receipt so the request is not delayed. Dropped receipts are counted and exposed in two places.

The X-PIT-Audit-Dropped header is included on all audited responses and all /v1/audit-log responses. It shows the total number of receipts the server process has dropped since startup. If the value does not change during a run, no receipts were lost.

$ curl -s -H "Authorization: Bearer pit_live_..." \
    https://api.pit.aqx.llc/v1/audit-log/stats

The queue metrics cover the entire server process rather than a single key, because dropped receipts are not attributed to a key ID. The default queue depth is 1200, which holds one full minute of requests at the Desk rate limit.

What is not recorded

Retention

The retention policy for Desk receipts is 400 days. This limit is currently not enforced, and receipts are kept indefinitely. Use format=jsonl to export and store receipts long term.

Limits

/v1/audit-log and /v1/audit-log/stats allow 60 requests per minute per account. This limit is separate from the standard /v1 limit on your plan. Requests above this limit return a 429 status code with a Retry-After header.

These two routes are not yet in openapi.json, so generated SDK clients do not include them. You must call them directly. The dashboard does not display receipts.