KERNIT Documentation
Live endpoint verification
Live verification proves that documented examples still match the production API. It should use safe sample DOCX files, scoped API keys, and a clear support record for every failed endpoint.
Verification Scope#
| Surface | Live check | Evidence to keep |
|---|---|---|
| Scan | POST /hyperlink-scan with a fixture DOCX. | scanFingerprint, match count, request id, status. |
| Resolve | POST /hyperlink-crossref with known references. | Resolved DOI count, held rows, request id, status. |
| Apply | POST /hyperlink-apply using scan state. | Linked DOCX returned, link count, request id, status. |
| One-step | POST /hyperlink only for predictable fixtures. | Linked DOCX returned, link count, request id, status. |
Credential Boundary#
Use a scoped test key, never a shared production customer key. Do not paste files, tokens, or request bodies into docs feedback. Support context should include endpoint, status, requestId, scanFingerprint, and settingsHash when available.
Verification Harness#
KERNIT_API_KEY="sk_kernit_live_..." \
KERNIT_DOCX_FIXTURE="./fixtures/live-smoke.docx" \
KERNIT_LIVE_VERIFY_MODE="scan" \
npm run docs:verify:liveThe harness defaults to a scan-only check so it can verify the documented production host without consuming apply allowance. Set KERNIT_LIVE_VERIFY_MODE=workflow only when the test account is allowed to run resolve and apply against the fixture.
Failure Triage#
| Failure | Interpretation | Next action |
|---|---|---|
| 400 | Fixture, settings, decisions, or multipart shape is wrong. | Fix the example or fixture before retesting. |
| 401 | Test key missing or invalid. | Rotate the key and rerun only the auth boundary. |
| 402 | Allowance or org billing state blocks apply. | Top up the test account or switch to a dedicated verification org. |
| 429 | Rate limit policy is active. | Respect retry_after and keep the run evidence. |
| 5xx | KERNIT availability or processing failure. | Capture requestId and route to production support. |
Runbook Output#
A verification run should produce a short record with date, API version, docs commit, fixture name, endpoints tested, status codes, request IDs, and whether the public docs need an update.