Agent Feedback Well-Known Service Discovery Endpoint

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

curl https://agent-feedback-api-production.up.railway.app/.well-known/agent-feedback-v1.json

Example response

{
  "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

string

Human-readable service name: "Agent Feedback Protocol".

number

Protocol version integer. Currently 1.

string

One-sentence description of what the service collects.

object

Describes the telemetry batching endpoint.

Show telemetry fields

string

The fully-qualified URL for POST /api/v2/telemetry/batches.

string

Human-readable description of the required authentication: the af_live_ company product key.

string

Delivery guarantee summary: "bounded, asynchronous, and non-blocking".

object

Describes the outcome submission endpoint.

Show outcomeSubmission fields

string

The fully-qualified URL for POST /api/v2/outcomes.

string

Human-readable description of the required authentication: the short-lived afr2_ capability token.

object

The two fields the agent must supply: outcome (one of success, partial, failure) and note (one sentence, max 500 characters).

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.

object

Direct download URLs for each SDK package and the raw protocol archive.

Show integrations fields

string

Node.js SDK .tgz package.

string

Python SDK .whl wheel.

string

Go SDK .tar.gz archive.

string

Rust SDK .tar.gz crate archive.

string

The full protocol v1 specification as a .zip archive, including JSON schemas and a conformance test vector.

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.

string

Privacy statement clarifying that agent identity is never required or asserted. customerRef and runtime hints are optional and opaque.

string

Data policy reminder embedded in the document: never submit prompts, transcripts, secrets, credentials, personal data, customer content, or raw tool payloads.

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.

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.

​Endpoint

​Legacy endpoint

​Example request

​Example response

​Response fields

​Use cases

Endpoint

Legacy endpoint

Example request

Example response

Response fields

Use cases