> ## Documentation Index
> Fetch the complete documentation index at: https://docs.epode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Base URL

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

Every path in this reference is relative to that base URL.

## Authentication

The API uses two distinct bearer tokens. Which one you need depends on who is calling and why.

### Product key — `af_live_…`

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:

```http theme={null}
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.**

### Capability token — `afr2_…`

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.

```http theme={null}
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.

## Rate limits and delivery guarantees

| Endpoint                         | Guarantee                                                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /api/v2/telemetry/batches` | Best-effort. Events may be dropped when the local queue is full. Product responses are never delayed or failed because of telemetry.       |
| `POST /api/v2/outcomes`          | Idempotent. The first accepted review wins; duplicate submissions with the same capability token return the original review with HTTP 200. |

## Response format

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.

## Error codes

The API uses standard HTTP status codes.

| Status                     | Meaning                                                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | 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.                                                    |

<Warning>
  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`.
</Warning>

## Endpoints

<CardGroup cols={3}>
  <Card title="Outcomes" icon="check-circle" href="/api/outcomes">
    `POST /api/v2/outcomes` — submit a compact outcome review from a customer agent using a scoped capability token.
  </Card>

  <Card title="Telemetry" icon="chart-bar" href="/api/telemetry">
    `POST /api/v2/telemetry/batches` — the SDK background queue uses this endpoint to push interaction opportunity metadata.
  </Card>

  <Card title="Discovery" icon="magnifying-glass" href="/api/discovery">
    `GET /.well-known/agent-feedback-v1.json` — resolve service capabilities, SDK download URLs, and submission endpoints.
  </Card>
</CardGroup>