Agent Feedback API Reference and Authentication Guide
Base URL, product key and capability token authentication, rate limits, response format, and error codes for the Agent Feedback REST API.
The Agent Feedback API is a small, protocol-first HTTP API that collects compact outcome reviews from autonomous AI agents. All public endpoints share a common base URL, a JSON response envelope, and standard HTTP status codes. This page covers everything you need before making your first request.
Your product key authenticates your backend server (or the SDK running inside it) when it pushes telemetry to the Agent Feedback service. Pass it as a standard Authorization header:
Authorization: Bearer af_live_<your_product_key>
Product keys have the following shape:
af_live_<32 lowercase hex key id>_<secret with at least 20 characters>
You create and revoke product keys in the Agent Feedback dashboard. Never expose the product key to customer agents or include it in product responses.
A capability token is a short-lived, single-use credential that the SDK signs locally for each eligible product response and embeds in the _agentFeedback contract. The customer’s autonomous agent uses this token — not the product key — to submit an outcome review.
Authorization: Bearer afr2_<capability_token>
Capability tokens:
Are signed with HMAC-SHA256 using a key derived from your product key.
Expire after two hours from issuance.
Are scoped to a single interaction ID.
Contain no customer data, prompts, or product payload.
The SDK generates capability tokens client-side. You never need to call the Agent Feedback API to mint one.
All responses use Content-Type: application/json. Successful responses return a JSON object specific to each endpoint. Error responses return a JSON object with at least an error field describing the problem.
Malformed JSON, unknown fields, or a field that the API explicitly rejects (for example, PII-shaped content in a note).
401 Unauthorized
The Authorization header is missing, the token is malformed, or a capability token is expired or revoked.
409 Conflict
Not used for outcome submissions — duplicates return 200 with the original review.
422 Unprocessable Entity
The request is well-formed JSON but fails validation — for example, outcome is not one of the allowed values, or note is shorter than 8 characters.
500 / 503 Server Error
An unexpected server fault. For 5xx errors on outcome submissions, retry once after a brief delay.
Do not retry outcome submissions more than once. The endpoint is idempotent, so a second attempt with the same capability token is safe — but the capability expires after two hours, so retries beyond that window will receive a 401.