Deniable
Log inBrowse datasets

Documentation

API reference.

Technical details for authenticated JSON retrieval, prepaid credits, delivery history, and safe integrations.

This reference describes the Deniable API contract. Use the API overview for the product model and pricing for current purchase details.

Deniable API reference

The Deniable API provides authenticated access to pre-generated synthetic test documents. Responses are JSON and include the document content plus catalogue metadata. API access uses prepaid credits and has no monthly subscription.

Availability

The public API contract is documented here before production credentials are issued. Endpoint availability, limits, and response fields are authoritative only after they are enabled for your account.

Base URL

https://api.deniable.net/v1

Production API traffic is separated from the marketing site on api.deniable.net. The API subdomain is the planned public endpoint; the site domain remains for the catalogue, account, and documentation.

Authentication

Create an account, then create an API key from the account dashboard. Send the key with every request:

Authorization: Bearer dk_live_your_key

API keys are shown once, stored as hashes, and can be revoked or replaced. Never commit a key to source control or expose it in browser code. Use a server-side environment variable such as DENIABLE_API_KEY.

Credits

  • One standard item costs 1 credit.
  • Long-form documents and ebooks cost 10 credits.
  • One credit costs €0.0025 (0.25 cents).
  • The minimum top-up is €5 (2,000 credits).
  • You choose the top-up amount; there are no fixed credit packages or recurring subscriptions.
  • A request is rejected before delivery when the balance is too low.
  • Credit reservations and delivery records are written atomically, so concurrent requests cannot create a negative balance.

    • Endpoints

    Try free samples

    POST /v1/samples

    After creating and verifying an account, create an API key and send an Idempotency-Key. You can retrieve up to five pre-generated sample documents per account without spending credits:

    { "category": "support-tickets", "count": 1 }

    The response has the same JSON document shape as a paid delivery and includes freeSample: true with creditsCharged: 0. The account-gated web sample page is available at https://deniable.net/free-sample.

    List catalogue items

    GET /v1/catalog

    Returns published API-enabled catalogue items. Use filters to keep the response small.

    Query parameters:

  • category: document category slug, for example support-tickets
  • language: language code, for example en
  • format: json, txt, or eml. PDF and other binary files are not delivered through the document API.
  • page: one-based page number
  • limit: number of items, capped by the account limit

    • Retrieve documents

    POST /v1/documents

    Request body:

    { "dataset": "support-tickets-en-json-starter", "count": 10, "excludeDelivered": true }

    The service selects documents from the requested published dataset. With excludeDelivered: true, it favours document IDs not previously delivered to the API key and starts a new cycle only after the available pool is exhausted. Re-fetching a document in a later cycle consumes credits again.

    Response shape:

    { "data": [{ "id": "doc_...", "content": {}, "category": "support-tickets", "language": "en", "format": "json", "creditCost": 1 }], "meta": { "requested": 10, "delivered": 10, "creditsCharged": 10, "nextCycle": false } }

    The content value follows the source format. JSON returns a parsed JSON value; TXT, EML, CSV, and SQL return the raw text string. PDFs and images are intentionally excluded from API delivery and remain inside paid ZIP downloads.

    Check usage

    GET /v1/usage

    Returns the current credit balance, total purchased credits, total consumed credits, and recent delivery totals for the authenticated account.

    API key management

    GET /v1/keys`, `POST /v1/keys`, and `DELETE /v1/keys/:id

    Keys are scoped to an account. A deleted key stops working immediately. The account dashboard is the preferred interface for creating and revoking keys.

    Rate limits

    Every key is rate-limited. The starting policy is 60 document requests per minute per key, 30 catalogue requests per minute per key, and a maximum of 1,000 documents per document request. Higher limits can be introduced for approved accounts. The active limit is returned in response headers:

  • RateLimit-Limit
  • RateLimit-Remaining
  • RateLimit-Reset

    • When the limit is exceeded, the API returns HTTP 429 and a Retry-After header. Use exponential backoff and do not retry a request indefinitely.

    Errors

    Errors use a stable JSON shape:

    { "error": { "code": "insufficient_credits", "message": "Add credits before requesting more documents.", "requestId": "req_..." } }

    Common status codes:

  • 400: invalid filters or request body
  • 401: missing or invalid API key
  • 403: key revoked or dataset not enabled for API delivery
  • 404: dataset or document route not found
  • 409: request could not be reserved safely; retry with a new request ID
  • 429: rate limit exceeded
  • 402: insufficient credits
  • 500: temporary service error; include the request ID when contacting support

    • Idempotency and retries

    For a request that creates a delivery, send a unique Idempotency-Key header. A repeated request with the same idempotency key returns the original result without charging twice. Using a different idempotency key intentionally creates a new delivery and charges credits again. Idempotency keys should be unique to the logical job you are retrying.

    cURL example

    curl -X POST https://api.deniable.net/v1/documents -H "Authorization: Bearer $DENIABLE_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: run-2026-09-03-001" -d '{"dataset":"support-tickets-en-json-starter","count":10,"excludeDelivered":true}'

    Data and licensing

    Deniable documents are synthetic and include deliberate variations. Check the individual catalogue release for its exact formats, fields, language coverage, document count, and licence. Internal development, QA, evaluation, and model training are permitted where the product licence says so. Redistribution, resale, public hosting, or presenting synthetic documents as real records is not permitted.

    Secure integration checklist

  • Keep API keys on your server, never in frontend JavaScript.
  • Request only the number of documents you need.
  • Store the returned request ID with your test run.
  • Handle 402 and 429 responses explicitly.
  • Use idempotency keys for retryable jobs.
  • Rotate keys when a team member or CI secret changes.

    • Get a step-by-step tutorial from your AI assistant

    Copy the prompt below and paste it into ChatGPT, Claude, or another AI assistant that can follow technical instructions. Then paste the full Deniable API reference after the prompt so the assistant has the exact endpoint details.

    Act as an integration expert for the Deniable API. Using the Deniable API reference I provide below, create a step-by-step tutorial that helps me integrate Deniable into my project. Write the tutorial in plain language, and include concrete example requests and responses. Cover these topics in order:
    1. Creating an account and API key
    2. Adding credits
    3. Making the first API request (list catalogue items)
    4. Retrieving documents
    5. Handling authentication, credits, rate limits, and errors
    6. Using idempotency keys for safe retries
    7. Practical no-code and low-code integration options with tools like Zapier or Make
    At the end, give me a simple checklist I can follow. If any information is missing from the reference, ask me before making assumptions.
    Here is the Deniable API reference:
    [PASTE THE FULL API REFERENCE HERE]