> ## 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 Well-Known Service Discovery Endpoint

> Resolve Agent Feedback service capabilities, SDK package download URLs, and submission endpoints via the versioned well-known discovery document.

The discovery endpoint returns a machine-readable JSON document that describes the Agent Feedback service: where to submit outcomes, how to push telemetry, which SDK packages are available for download, and what the protocol's privacy and reliability guarantees are. Feedback-aware runtimes and the `agent-feedback-doctor` CLI use this document to resolve the submission URL and verify that the service is reachable before running integration checks.

## Endpoint

```
GET /.well-known/agent-feedback-v1.json
```

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

No authentication is required. The endpoint is publicly accessible.

## Legacy endpoint

The original discovery path is still supported and will continue to return a response, but it is deprecated:

```
GET /.well-known/agent-feedback.json
```

The legacy response sets `"deprecated": true` and includes a `"replacement"` field pointing to the v1 URL. Update any tooling or hardcoded references to use `/.well-known/agent-feedback-v1.json` instead.

## Example request

```bash theme={null}
curl https://agent-feedback-api-production.up.railway.app/.well-known/agent-feedback-v1.json
```

## Example response

```json theme={null}
{
  "name": "Agent Feedback Protocol",
  "version": 1,
  "purpose": "Collect one compact product-outcome review from a customer's independent agent.",
  "telemetry": {
    "url": "https://agent-feedback-api-production.up.railway.app/api/v2/telemetry/batches",
    "authentication": "Bearer af_live_... company product key",
    "delivery": "bounded, asynchronous, and non-blocking"
  },
  "outcomeSubmission": {
    "url": "https://agent-feedback-api-production.up.railway.app/api/v2/outcomes",
    "authentication": "Bearer afr2_... short-lived interaction capability",
    "requiredFields": {
      "outcome": ["success", "partial", "failure"],
      "note": "one short sentence, at most 500 characters"
    }
  },
  "classification": {
    "http": "unclassified until an outcome is submitted",
    "mcp": "confirmed immediately by protocol tool use"
  },
  "integrations": {
    "node": "https://agent-feedback-api-production.up.railway.app/static/agent-feedback-node-0.1.0.tgz",
    "python": "https://agent-feedback-api-production.up.railway.app/static/agent_feedback-0.1.0-py3-none-any.whl",
    "go": "https://agent-feedback-api-production.up.railway.app/static/agent-feedback-go-0.1.0.tar.gz",
    "rust": "https://agent-feedback-api-production.up.railway.app/static/agent-feedback-rust-0.1.0.tar.gz",
    "protocol": "https://agent-feedback-api-production.up.railway.app/static/agent-feedback-protocol-v1.zip"
  },
  "reliability": {
    "http": "best effort for generic agents; deterministic with a feedback-aware runtime",
    "mcp": "protocol-backed explicit outcome tool"
  },
  "identity": "Agent identity is neither required nor claimed. customerRef and runtime hints are optional opaque context.",
  "privacy": "Never submit prompts, transcripts, secrets, credentials, personal data, customer content, or raw tool payloads."
}
```

## Response fields

<ResponseField name="name" type="string">
  Human-readable service name: `"Agent Feedback Protocol"`.
</ResponseField>

<ResponseField name="version" type="number">
  Protocol version integer. Currently `1`.
</ResponseField>

<ResponseField name="purpose" type="string">
  One-sentence description of what the service collects.
</ResponseField>

<ResponseField name="telemetry" type="object">
  Describes the telemetry batching endpoint.

  <Expandable title="telemetry fields">
    <ResponseField name="telemetry.url" type="string">
      The fully-qualified URL for `POST /api/v2/telemetry/batches`.
    </ResponseField>

    <ResponseField name="telemetry.authentication" type="string">
      Human-readable description of the required authentication: the `af_live_` company product key.
    </ResponseField>

    <ResponseField name="telemetry.delivery" type="string">
      Delivery guarantee summary: `"bounded, asynchronous, and non-blocking"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="outcomeSubmission" type="object">
  Describes the outcome submission endpoint.

  <Expandable title="outcomeSubmission fields">
    <ResponseField name="outcomeSubmission.url" type="string">
      The fully-qualified URL for `POST /api/v2/outcomes`.
    </ResponseField>

    <ResponseField name="outcomeSubmission.authentication" type="string">
      Human-readable description of the required authentication: the short-lived `afr2_` capability token.
    </ResponseField>

    <ResponseField name="outcomeSubmission.requiredFields" type="object">
      The two fields the agent must supply: `outcome` (one of `success`, `partial`, `failure`) and `note` (one sentence, max 500 characters).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="classification" type="object">
  Explains how interactions are classified per surface.

  * `"http"` — starts as `unclassified`; promoted to `confirmed` when an outcome review arrives.
  * `"mcp"` — always `confirmed` immediately because the agent calls the registered tool explicitly.
</ResponseField>

<ResponseField name="integrations" type="object">
  Direct download URLs for each SDK package and the raw protocol archive.

  <Expandable title="integrations fields">
    <ResponseField name="integrations.node" type="string">
      Node.js SDK `.tgz` package.
    </ResponseField>

    <ResponseField name="integrations.python" type="string">
      Python SDK `.whl` wheel.
    </ResponseField>

    <ResponseField name="integrations.go" type="string">
      Go SDK `.tar.gz` archive.
    </ResponseField>

    <ResponseField name="integrations.rust" type="string">
      Rust SDK `.tar.gz` crate archive.
    </ResponseField>

    <ResponseField name="integrations.protocol" type="string">
      The full protocol v1 specification as a `.zip` archive, including JSON schemas and a conformance test vector.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reliability" type="object">
  Per-surface reliability summary.

  * `"http"` — best effort for generic agents; deterministic when the consuming runtime explicitly handles the `_agentFeedback` contract.
  * `"mcp"` — protocol-backed through the registered `report_product_outcome` MCP tool.
</ResponseField>

<ResponseField name="identity" type="string">
  Privacy statement clarifying that agent identity is never required or asserted. `customerRef` and runtime hints are optional and opaque.
</ResponseField>

<ResponseField name="privacy" type="string">
  Data policy reminder embedded in the document: never submit prompts, transcripts, secrets, credentials, personal data, customer content, or raw tool payloads.
</ResponseField>

## Use cases

**`agent-feedback-doctor` CLI** — the CLI fetches this document to verify that the service is reachable, resolve the correct submission URL, and confirm that your product key can reach the telemetry endpoint before you deploy.

**Feedback-aware runtimes** — runtimes that natively understand the Agent Feedback protocol read this document to discover the submission URL dynamically rather than hardcoding it. This means you can point a runtime at any compatible Agent Feedback deployment by changing one environment variable.

**SDK bootstrapping** — the `integrations` field gives installers and setup scripts direct download URLs for every supported language without requiring a registry lookup.

<Note>
  The `/.well-known/agent-feedback.json` legacy endpoint sets `"deprecated": true` and `"writesEnabled": false` in its response. If your tooling reads this document and sees `deprecated: true`, update its configuration to use the v1 URL.
</Note>