Send Telemetry Batches — POST /api/v2/telemetry/batches

The telemetry batches endpoint receives interaction opportunity metadata that the SDK enqueues locally and ships in the background. Your product responses never wait for this call — the SDK drains its queue asynchronously at a 500 ms interval, or sooner when 50 events accumulate. You do not need to call this endpoint yourself: the SDK handles everything automatically.

The SDK handles batching automatically. You only need this endpoint if you are implementing a custom SDK or porting to a new language.

Endpoint

POST /api/v2/telemetry/batches

Base URL: https://agent-feedback-api-production.up.railway.app

Authorization

Use your company product key. This key stays on your backend and is never passed to customer agents.

Authorization: Bearer af_live_<your_product_key>

Queue behavior

The SDK maintains a bounded in-memory queue (default: 1,000 events). When the queue is full, the oldest event is dropped to make room for the new one — product responses are never delayed or failed as a result. Batches are sent with a 3-second HTTP timeout; if delivery fails, the SDK retries each event up to three times before discarding it. A single warning is logged the first time delivery fails.

Request body

Send a JSON object with a single events array. Each batch may contain between 1 and 100 events.

array

required

An array of interaction telemetry event objects. Minimum 1, maximum 100 per batch.

Show Event object fields

string

required

UUID v4 identifier for the interaction. Generated by the SDK when it prepares the _agentFeedback envelope. Used to correlate telemetry with a later outcome review.

string

required

The surface through which the agent consumed the product response.Allowed values:

"http_json" — a JSON API response
"http_html" — an HTML page response
"http_headers" — a response where the envelope was delivered via headers (arrays, scalars, binary bodies)
"mcp" — an MCP tool call response

string

required

The normalized route path, with dynamic segments replaced by :id. For example, /orders/:id or /search. Must be between 1 and 160 characters.The SDK derives this automatically by replacing UUIDs and numeric path segments. If you are building a custom SDK, apply the same normalization before sending.

string

required

The initial interaction classification.

"unclassified" — HTTP surfaces start here; they are promoted to "confirmed" when an outcome review arrives.
"confirmed" — MCP tool calls are confirmed immediately at the time of use.

string

required

ISO 8601 timestamp (with timezone) for when the interaction occurred, e.g. "2026-07-28T04:00:00.000Z".

number

The HTTP status code of the product response, e.g. 200. Must be between 100 and 599.

number

How long the product API took to respond, in milliseconds. Must be ≥ 0.

string

An opaque reference to the customer in your own system, for example a hashed user ID. Must be between 1 and 160 characters. Never send an email address, name, or any other PII.

string

An observed agent runtime identifier, such as a User-Agent header value or MCP client name hint. This is explicitly unverified and is never presented as agent identity. Must be between 1 and 200 characters.

string

How the runtime hint was observed. Allowed values: "http", "mcp".

string

An opaque reference linking this interaction to a broader agent session in your system. Must be between 1 and 160 characters.

string

How the session reference was established. Allowed values: "customer", "mcp", "continuation".

string

How the interaction was confirmed. Currently the only accepted value is "mcp".

Example request

curl -X POST https://agent-feedback-api-production.up.railway.app/api/v2/telemetry/batches \
  -H "Authorization: Bearer af_live_<your_product_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "interactionId": "b3e2f1a0-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
        "surface": "http_json",
        "operation": "/search",
        "statusCode": 200,
        "durationMs": 142,
        "classification": "unclassified",
        "occurredAt": "2026-07-28T04:00:00.000Z"
      }
    ]
  }'

{
  "events": [
    {
      "interactionId": "b3e2f1a0-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
      "surface": "http_json",
      "operation": "/search",
      "statusCode": 200,
      "durationMs": 142,
      "classification": "unclassified",
      "occurredAt": "2026-07-28T04:00:00.000Z"
    }
  ]
}

Response

The server returns HTTP 202 Accepted with a count of how many events were stored.

{
  "accepted": 1,
  "dropped": 0
}

number

The number of events from this batch that were successfully ingested.

number

The number of events from this batch that were discarded (for example, because they failed internal validation). Currently always 0 for valid batches.

Error responses

Status	Cause
`400 Bad Request`	Malformed JSON, unknown fields at the batch or event level, or a field value outside the allowed schema.
`401 Unauthorized`	The `Authorization` header is missing, malformed, or the product key has been revoked.
`422 Unprocessable Entity`	The request is valid JSON but fails schema validation — for example, a `surface` value not in the allowed enum.
`503 Service Unavailable`	Transient server issue. The SDK will retry automatically.

Implementing a custom SDK

If you are porting Agent Feedback to a new language, your implementation must satisfy these requirements for the telemetry queue:

Non-blocking — enqueue the event synchronously; flush asynchronously. Never await the HTTP call inside a request handler.
Bounded — cap the queue at a fixed size (recommended: 1,000 events). Drop the oldest event when the queue is full rather than growing unbounded.
Batched — accumulate events and flush up to 50 at a time. Flush when 50 events accumulate, or after at most 500 ms, whichever comes first.
Retry-limited — retry failed batches up to 3 times. Discard after that to avoid memory growth.
Schema-conformant — normalize operation paths (replace UUIDs and bare numeric segments with :id) and only send the fields defined in telemetry-batch.schema.json.

See the protocol conformance requirements for the full list.

​Endpoint

​Authorization

​Queue behavior

​Request body

​Example request

​Response

​Error responses

​Implementing a custom SDK

Endpoint

Authorization

Queue behavior

Request body

Example request

Response

Error responses

Implementing a custom SDK