Drazill API Documentation

“Conforms to the Drazill v1 API” should be a check, not a claim. The conformance pack is a runnable suite you point at staging with a test key; it prints a PASS/FAIL table and writes a machine-readable conformance-report.json. A conformance badge is a link to that report — nothing more, and nothing less.

pip install drazill-conformance
drazill-conformance run \
  --base-url https://staging.drazill.com/api/v1 \
  --api-key "$DRAZILL_TEST_KEY" \
  --report conformance-report.json

Run it against staging with a drzl_test_ key. The suite deliberately provokes 401/404/422/429 responses and posts an idempotent mutation, so a production host — or a drzl_live_ key — is refused unless you explicitly pass --live-i-know. See Get an API key to mint a test key.

What the pack checks

drazill-conformance list prints every check id and title. Three named groups:

Group	What it asserts
`rest`	`X-API-Key` semantics (401 anonymous, 401 on a bad key, 200 with a key); the error envelope on 404/422; a 429 carrying `Retry-After`; a cursor walk that neither repeats rows nor fails to terminate; the `Idempotency-Replayed` marker on a retried mutation; the pinned spec’s strong `ETag` and its `304` on `If-None-Match`.
`realtime`	The published-envelope key set as exact set equality; the canonical event vocabulary, with deprecated aliases normalizing; per-channel sequences strictly increasing with no gaps; a paged resync covering every missed sequence exactly once.
`webhooks`	HMAC signature vectors generated from the canonical scheme — valid, mid-rotation multi-candidate, tampered body, wrong secret, stale and future timestamps, swapped delivery id, empty signature.

The realtime literals in the pack are vendored byte-for-byte from the frozen contract the platform’s own suite pins, with a drift gate that fails the build if the two ever differ. The pack cannot check against a contract nobody upholds.

Checking your own webhook verifier

The vectors carry the verdict a correct implementation must reach, so they work against code we have never seen:

drazill-conformance vectors --out vectors.json     # inspect the pack
drazill-conformance verify --command './my-verifier.sh'

Your command runs once per vector with a JSON file path as its last argument: exit 0 for “valid”, exit 1 for “invalid”. Any other status is reported as a failure rather than guessed at.

The vector worth your attention is stale_timestamp: the digest is correct and only the timestamp is outside tolerance. A verifier that checks the HMAC but not the clock accepts replayed deliveries and passes every other test you are likely to have written.

The badge grammar

A badge is a sentence, and each part of it is load-bearing. Use one of exactly two forms.

Community clients — anyone who runs the pack against their own integration:

Drazill API v1 · conformance-pack 2026-07-29 · self-reported

First-party SDKs — the clients in this repository, whose fixture run is executed by our CI on every change:

Drazill API v1 · conformance-pack 2026-07-29 · first-party · CI-verified

Part	Means
`Drazill API v1`	Which contract — the versioned public API, not a product tier.
`conformance-pack <date>`	The contract date the pack pinned, taken verbatim from `suite.contract_date` in your report. Never today’s date, never a version you chose.
`self-reported`	You ran it and you are stating the result. Nobody at Drazill observed or reviewed the run.
`first-party · CI-verified`	Reserved for clients in the Drazill repository, where the run happens in our CI. It is a statement about who ran it, not a quality tier.

Do not alter the grammar. A badge that reads “certified”, “approved”, “guaranteed”, “official”, “partner”, or “verified by Drazill” is claiming something no test run can support, and we will ask you to change it.

What a badge does not mean

Plainly, so there is nothing to read between the lines:

It is a test result you are reporting, not an endorsement, certification, approval, partnership, or affiliation.
It says the checks in the pack passed at the moment you ran them, against the contract date named in the badge. It says nothing about your uptime, correctness outside those checks, security, or fitness for any purpose.
Passing every check does not mean the integration is complete — the pack covers the contract surfaces listed above, not your product.
We do not review, approve, or maintain a registry of community badges. There is no application and nothing to apply for.
A SKIP is not a pass. If a check could not run, the report says so and the badge still only claims what the report shows.

Attach the report

A badge without its report is decoration. Link the badge image to the conformance-report.json your run produced — a raw file URL, a CI artifact, or a gist all work. The report records the target, the mode, the timestamp, the contract date, and every check’s verdict, so a reader can see what your badge is standing on.

{
  "report_schema_version": "1.0.0",
  "suite": { "name": "drazill-conformance", "version": "2026-07-29", "contract_date": "2026-07-29" },
  "run": { "target": "https://staging.drazill.com/api/v1", "mode": "live" },
  "summary": { "passed": 13, "failed": 0, "skipped": 0 },
  "result": "passed"
}

Markdown, for a README:

[![Drazill API v1 · conformance-pack 2026-07-29 · self-reported](https://img.shields.io/badge/Drazill_API_v1-conformance--pack_2026--07--29_%C2%B7_self--reported-18181b)](https://example.com/your/conformance-report.json)

Re-verification

The contract date in a badge is what makes it honest, and what makes it expire.

Re-run the pack when the contract date bumps. The date changes only when the pinned contract changes, and every bump is announced in the changelog — that is the signal to re-run.
Update the badge to the new date, or leave the old one and let it show its age. An old date is honest; a current date over an old run is not.
A badge quoting a contract date is a claim about that revision. It does not silently roll forward, and nothing in the pack will roll it forward for you.

First-party badges

The Python and TypeScript SDKs in this repository carry the first-party · CI-verified badge. Their fixture run and the pack’s own tests execute in CI on every change to either the pack or the frozen contract, and a drift between the two fails the build. The badges link to the workflow that runs them — the same evidence you are asked to attach.