API reference · Wire version 1

Agent Traffic API reference

The public request contract for privacy-bounded completed-request telemetry. Access remains approval-based during Developer Preview.

Download OpenAPI Request API access

Endpoint

POST https://www.tryreadable.ai/api/external-agentic/traffic/batches

Requests must use HTTPS, application/json, identity content encoding, and a body no larger than one MiB.

Authentication and headers

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_TRAFFIC_WRITE_KEY`. Store only in trusted server infrastructure.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Yes	Must exactly equal `batch_id` and remain stable on retry.
`X-Readable-Ingestion-Version`	No	If supplied, must be `1`.

Batch envelope

Field	Type	Presence	Rules
`schema`	string	Required	Must be readable.external-agentic.traffic.
`version`	integer	Required	Must be 1.
`site_id`	string	Required	Site identity issued by Readable; maximum 128 characters.
`batch_id`	string	Required	Stable batch identity; must equal Idempotency-Key.
`created_at`	date-time	Required	UTC batch-creation time.
`source`	object	Required	Registered source type, provider, integration ID, collector, and collector version.
`event_count`	integer	Required	Must equal events.length; from 1 to 500.
`events`	array	Required	One to 500 completed-request events.

Registered source

source.type is one of cdn_log, edge_event, server_log, or application_event. Its type, lowercase provider, and stable integration ID must exactly match the credential registration.

Traffic event

Every event represents one completed request and requires:

event_id: stable for the same source event across every retry or re-batching.
occurred_at: UTC completion time, no more than five minutes in the future and no more than 90 days old.
request: request ID, method, HTTPS scheme, exact hostname, path-only URL, and non-empty user agent.
response: HTTP status plus optional content type, duration, and bytes sent.
delivery: optional Readable delivery outcome facts when the source actually has them.
extensions: optional, but version 1 accepts only an empty object.

Valid events can be accepted even when other events in the batch are rejected. Use each error's event index and optional event ID to quarantine or correct only the affected event.

Privacy boundary

The API intentionally accepts a closed allowlist. Do not send:

request or response bodies;
cookies or authorization headers;
raw IP addresses or fingerprints derived for cross-service tracking;
raw query strings or URL fragments;
arbitrary request or response headers;
credentials embedded in referrer URLs.

Paths must begin with “/” and contain no “?” or “#”. Strip the query and fragment before durable local storage as well as before submission.

Successful receipt

A successful HTTP response is trustworthy only when all of the following are true:

success and accepted are exactly true;
site_id and batch_id match the submitted batch;
event_count equals the submitted count;
event_count = inserted + deduplicated + rejected;
every error has a valid event index and safe code.

If the body is missing, malformed, truncated, or fails any identity/accounting check, retain the unchanged batch and treat the attempt as retryable.

HTTP status handling

Status	Meaning	Collector action
`200`	Batch completed	Validate site_id, batch_id, event_count, inserted, deduplicated, rejected, and errors before deleting local work.
`400`	Invalid request	Fix and quarantine an invalid envelope. Do not blindly retry unchanged content.
`401`	Unauthorized	Pause delivery, repair or rotate the credential, then explicitly resume.
`403`	Disabled or unauthorized	Pause delivery and ask Readable to verify the site and registered source binding.
`409`	Conflict or processing	Retry an in-progress response; quarantine a permanent ID/content conflict.
`413`	Payload too large	Split a multi-event batch under new batch IDs while preserving every event ID.
`415`	Unsupported media type	Pause and send uncompressed application/json.
`429`	Rate limited	Retain the batch and retry after the provided bounded delay.
`503`	Temporarily unavailable	Retain the batch and retry with exponential backoff and jitter.

Idempotency and retry

Retry a batch with the same batch ID, event IDs, order, and normalized facts.
Never resolve an identity conflict by inventing a new event ID for data already persisted under another identity.
Use bounded exponential backoff with jitter for network errors, malformed acknowledgements, eligible 409, 429, and 5xx.
Honor safe Retry-After values, subject to a bounded local maximum.
Do not follow redirects with the authorization header.

Exact batch receipts are retained for at least 30 days. Event identity protection is checked for at least 180 days.

Version 1 limits

One to 500 events per batch.
One MiB maximum uncompressed JSON body.
No gzip request bodies.
HTTPS request facts only.
Maximum 100 event errors returned; errors_truncated=true indicates additional rejections.

Future incompatible changes will use a new API version. Readable will not silently reinterpret version 1 payloads.