Developer Preview · API version 1

Universal Agent Traffic API

Send safe completed-request telemetry from your infrastructure. Readable normalizes, deduplicates, and classifies the traffic centrally—your team does not need to maintain its own agent-detection rules.

Start the quickstart View API reference Request API access

How it works

Your collection point observes a completed web request, extracts only the allowed facts, stores the event durably, and submits it to Readable in a batch. Submission happens after the visitor response and must never make your website depend on Readable availability.

Collect completed-request facts

Use your CDN, edge runtime, reverse proxy, application middleware, or log pipeline.

Remove prohibited data

Send path-only request facts. Never send bodies, cookies, credentials, raw IP addresses, or raw query strings.

Buffer outside the response path

Persist stable event IDs and group one to 500 events into a batch.

Submit and validate the receipt

Delete local work only after the response identity and every event count reconcile exactly.

This is not request proxying. Readable receives asynchronous telemetry and never returns the webpage response for this API.

Quickstart

Approved integrations receive a site ID, registered integration ID, exact authorized hostname, and a server-side key scoped only to traffic:write.

Set READABLE_INGESTION_KEY, READABLE_SITE_ID, and READABLE_INTEGRATION_ID in your server environment.
Replace the example hostname with the exact hostname approved during onboarding.
Generate stable batch, event, and request identities from your durable source record.
Submit a sandbox event and verify the complete acknowledgement before deleting it locally.

curl --request POST \
  https://www.tryreadable.ai/api/external-agentic/traffic/batches \
  --header "Authorization: Bearer $READABLE_INGESTION_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: batch:YOUR_STABLE_BATCH_ID" \
  --header "X-Readable-Ingestion-Version: 1" \
  --data '{
    "schema": "readable.external-agentic.traffic",
    "version": 1,
    "site_id": "YOUR_SITE_ID",
    "batch_id": "batch:YOUR_STABLE_BATCH_ID",
    "created_at": "2026-09-20T10:00:00Z",
    "source": {
      "type": "server_log",
      "provider": "generic",
      "integration_id": "YOUR_INTEGRATION_ID",
      "collector": "your-collector",
      "collector_version": "1.0.0"
    },
    "event_count": 1,
    "events": [{
      "event_id": "evt:YOUR_STABLE_EVENT_ID",
      "occurred_at": "2026-09-20T09:59:58Z",
      "request": {
        "request_id": "request:YOUR_REQUEST_ID",
        "method": "GET",
        "scheme": "https",
        "hostname": "www.example.com",
        "path": "/products/example",
        "user_agent": "ChatGPT-User/1.0",
        "referrer_url": "https://chatgpt.com/"
      },
      "response": {
        "status": 200,
        "content_type": "text/html",
        "duration_ms": 84,
        "bytes_sent": 18422
      },
      "extensions": {}
    }]
  }'

The command above demonstrates the wire format. A production collector must add durable buffering, bounded retry and backoff, restart recovery, safe handling for 413, and strict acknowledgement validation.

Sample code

Each standalone example disables credential-bearing redirects, uses a bounded request timeout, and validates the receipt identity and accounting. They are protocol examples—not platform-specific connectors.

cURL JavaScript Python Go Java PHP C#

Before production

Collect only after the request has completed and the response facts are known.
Keep submission outside the visitor response path.
Use one registered source identity and one scoped credential per integration.
Persist work before attempting delivery and retain it through retryable failures.
Preserve the same batch and event IDs on retry.
Monitor oldest backlog age, rejected events, retry rate, ingestion delay, and analytics parity.

Continue to the complete API reference →

Request Developer Preview access

Access is currently reviewed by the Readable team. We will confirm the collection point, privacy boundary, expected traffic volume, hostname, sandbox plan, and operational owner before issuing credentials.

Request API access