API Reference

Quickstart

1. Get an API key. Sign up for Plus ($39/mo) or higher, or top up a PAYG balance. Keys live in your dashboard.
2. Set the bearer header. Send Authorization: Bearer dad_live_... on every request except /v1/health.
3. Make your first detection. POST to /v1/detect with a JSON body containing text (min 50 words for a verdict, 150+ recommended for high confidence).
4. Read the verdict. Response includes score (0-1), band (categorical), per-layer scores, and a pricing_quote showing both billing modes.

Official SDKs

One-liner install in either language. Both wrap the same OpenAPI spec, ship type definitions, and handle retries + error mapping for you.

npm install @deepaidetector/client

pip install deepaidetector

Other languages: use the curl / Go / Ruby / PHP / C# samples below — every endpoint is a plain JSON POST/GET.

Authentication

Every request needs a bearer token in the Authorization header.

Authorization: Bearer dad_live_xxxxxxxxxxxx

Live keys start with dad_live_; sandbox / test keys (no real billing, capped quota) start with dad_test_. Issue, rotate, and revoke from your dashboard. Keys are shown in plaintext exactly once — at creation time. We only store a hash; if you lose a key you'll need to revoke and create a new one.

Code samples

Example: POST /v1/detect. The shape is identical for every other endpoint — change the path + body.

curl -X POST https://api.deepaidetector.com/v1/detect \
  -H "Authorization: Bearer $DEEPAIDETECTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Climate change is reshaping how coastal cities approach long-term planning. Rising sea levels and intensifying storms have moved infrastructure resilience from a niche topic to the top of every mayor agenda.",
    "strictness": "balanced"
  }'

Rate limits

Limits enforced at the edge. Three headers and a meta.rate_limit object are returned on every response:

X-RateLimit-Limit:     5000
X-RateLimit-Remaining: 4892
X-RateLimit-Reset:     1717948800000

When rate-limited, the API returns 429 with a Retry-After header (seconds) and a resets_at field (unix ms). Recommended client strategy: exponential backoff with jitter, respect Retry-After, cap at 3 retries. The official SDKs do this automatically.

Errors

All errors return { "error": "<machine_code>", "message": "<human>", "request_id": "<uuid>" }. Switch on error, not message — only error is part of the API contract.

Full error reference →

Webhooks

Configure a webhook URL in your dashboard (Plus+) to receive events when detections complete. Body is JSON; signature is HMAC-SHA256 over the body in the X-DAD-Signature header.

POST https://your-app.example.com/dad-webhook
X-DAD-Signature: a8f2e9...
X-DAD-Event:     detection.completed
X-DAD-Delivery:  0190b1f8-aae5-7e3a-9b1c-7f4ba2c0d3e1
Content-Type:    application/json

{
  "id": "evt_01J...",
  "type": "detection.completed",
  "created": 1717948800000,
  "data": { /* same shape as POST /v1/detect response */ }
}

Retry policy: 7 attempts with exponential backoff over 72h. Respond 2xx within 10s to ack.

Webhook signing + handler examples →