Developer docs

The BotWitness API

A tamper-evident record of what sites told AI crawlers. Auth with an API key from your dashboard: Authorization: Bearer <key> or ?key=<key>.

Lookup: GET /permission

Current or as-of-date verdict for a domain + AI crawler. Current/recent (30 days) is free; older dates need a Monitoring plan. Coverage (tracking_since) is always free.

curl "https://bot-witness.com/permission?domain=nytimes.com&agent=GPTBot&as_of=2024-06-01" \
  -H "Authorization: Bearer $KEY"

Certificate: GET /permission/certificate key

Returns a signed Certificate of Capture PDF for the record on a date. Consumes one certificate credit (unlimited on Monitoring).

curl "https://bot-witness.com/permission/certificate?domain=nytimes.com&agent=GPTBot" \
  -H "Authorization: Bearer $KEY" -o certificate.pdf

History: GET /history

Timeline of directive states for a domain (full history on Monitoring; 30-day window otherwise).

curl "https://bot-witness.com/history?domain=nytimes.com&agent=ClaudeBot" -H "Authorization: Bearer $KEY"

Change feed: GET /changes

curl "https://bot-witness.com/changes?domain=nytimes.com&since=2026-01-01"

Coverage: GET /coverage free

curl "https://bot-witness.com/coverage?domain=nytimes.com"

Change alerts: POST /subscriptions Monitoring

Get notified when a tracked domain changes its AI directives, by email ("kind":"email") or an HMAC-signed webhook. Webhook verify: sha256 = HMAC(secret, X-PR-Timestamp + "." + body).

curl -X POST https://bot-witness.com/subscriptions -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"email","endpoint":"[email protected]","domains":"nytimes.com,reddit.com"}'

Compliance attestation: GET /attestation Monitoring

The AI-operator artifact: what robots.txt permitted a named crawler across up to 100 domains over a date range, per-capture verdicts, JSON or filing-ready PDF. See the product page.

curl "https://bot-witness.com/attestation?agent=GPTBot&domains=nytimes.com,wsj.com&from=2026-01-01&to=2026-07-01&format=pdf" \
  -H "Authorization: Bearer $KEY" -o attestation.pdf

Violation check: POST /violations Monitoring

Paste server-log hits (structured, or raw Apache/nginx lines); each is judged against the robots.txt capture in effect at its timestamp, RFC-9309 path matching. Stateless, hits are never stored.

curl -X POST https://bot-witness.com/violations -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yoursite.com","agent":"GPTBot","hits":[{"time":"2026-07-10T06:12:01Z","path":"/private/x","agent":"GPTBot"}]}'

Compliance audit: POST /audit Audit / Monitoring

The productized violation check: the same stateless evaluation, aggregated into a citable report, per-crawler findings, disallowed-hit exhibits, and every governing snapshot cited. See the product page.

curl -X POST https://bot-witness.com/audit -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yoursite.com","agent":"GPTBot","log":"<raw access-log lines>","format":"pdf"}' \
  -o compliance-audit.pdf

Exposure report: POST /exposure Exposure / Monitoring

Probe AI models for reproduction of your work. Returns a tiered report (verbatim reproduction facts + a calibrated membership signal), an investigative signal, never a fabricated probability. See the product page. GET /exposure/config lists the models probed and the caps.

curl -X POST https://bot-witness.com/exposure -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"work_title":"My Novel","corpus":"<paste your text>","acknowledge":true}'
# add "format":"pdf" (or ?format=pdf) for the filing-ready PDF
# add "mode":"contamination" to run the same probes as a Benchmark Contamination Report

Opt-out efficacy report: POST /optout/report Opt-Out / Monitoring

The archive × probes flagship: your domain's dated, timestamped opt-out record joined with reproduction/recognition probes of the models released since. See the product page.

curl -X POST https://bot-witness.com/optout/report -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yoursite.com","corpus":"<paste your text>","acknowledge":true,"format":"pdf"}' \
  -o optout-efficacy.pdf

GPAI disclosure report: POST /gpai/report GPAI / Monitoring

The EU AI Act Art. 53(1)(d) record as a filing-ready artifact: every dated revision of each watched disclosure surface, cadence vs the six-month yardstick, optional term search in the latest published text. See the product page.

curl -X POST https://bot-witness.com/gpai/report -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"terms":["yoursite.com"],"format":"pdf"}' -o gpai-disclosure-report.pdf

Copyright traps: /exposure/traps Exposure / Monitoring

Publish a timestamped random canary (POST, body {work_title?}), list yours with last probe results (GET), re-probe the models on demand (GET /exposure/traps/<id>/probe). The daily watch re-captures the public page for free; Exposure Monitoring re-probes models automatically.

Exposure monitoring: /exposure/watches Exposure Monitoring

Enroll a work for recurring probes: re-run automatically when the model roster changes or monthly, with email alerts on deltas. GET lists watches, POST enrolls ({work_title, corpus, acknowledge}), POST /exposure/watches/<id>/run re-probes now (rate-limited), DELETE /exposure/watches/<id> stops.

Watch streams: GET /watch, GET /watch/history free coverage

The non-domain evidence streams: gpai (EU training-data disclosures), wba (agent signing-key directories), mcp / mcp-tools (registry entries and live tool manifests), hf (Hugging Face model license/gating state).

curl "https://bot-witness.com/watch?kind=hf&q=llama"
curl "https://bot-witness.com/watch/history?kind=wba&key=chatgpt.com"

Report: GET /report.json free

Aggregate stats behind the public report.

Evidence packages: per matter

Litigation-grade ZIP (captures, RFC-3161 tokens, Merkle proofs, standalone verifier) for a domain and date range, operator-delivered. See the service page.