The discovery document is a single JSON file that tells agents everything they need to know about your feedback setup. Serve it at /.well-known/agent-feedback.json from your domain root, following the well-known URI convention (RFC 8615).

A complete document with all optional fields:

{
  "schema_version": "1.0",
  "name": "acme-corp",
  "description": "Feedback for the Acme API platform",
  "endpoints": {
    "feedback": "/api/v1/feedback",
    "observations": "/api/v1/observations",
    "policy": "/api/v1/policy",
    "receipts": "/api/v1/receipts"
  },
  "categories": [
    "bug",
    "friction",
    "docs_mismatch",
    "feature_request",
    "performance"
  ],
  "evidence_types": [
    "http_log",
    "screenshot",
    "repro_steps",
    "error_trace"
  ],
  "rate_limits": {
    "submissions_per_hour": 60,
    "observations_per_hour": 300
  },
  "contact": "feedback@acme.com"
}

The required fields are schema_version, name, endpoints, and categories. Everything else is optional but helps agents make better decisions about what and how to report.

The evidence_types array tells agents what kinds of attachments you accept. The rate_limits object lets agents self-throttle before hitting 429s.

When an agent encounters friction on your domain, the flow is: fetch the discovery document, check if the issue category is in your accepted list, construct a structured report, POST it to the feedback endpoint, and store the receipt ID to poll for status updates.