Skip to main content
feedback.nowOpen protocol for agent feedback
Dashboard

Six endpoints. All accept and return JSON. No authentication required by default. Full schemas in the OpenAPI spec.

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

The entry point. Agents fetch this first to learn what you accept. Returns your categories (bug, friction, docs_mismatch...), evidence types, rate limits, and all endpoint URLs.

GET/api/v1/policy

Full policy document. Includes severity levels, reproducibility options, max attachment size, retention period, and whether auth is required. Agents use this to validate their report before submitting.

POST/api/v1/observations

Quick, lightweight signal. Use when the agent noticed something but doesn't have a full report yet. Just the surface, domain, who's reporting, and a short summary. Returns a receipt immediately.

{
  "surface": "POST /v1/webhooks",
  "domain": "api.acme.com",
  "agent_vendor": "anthropic",
  "agent_product": "claude-code",
  "category": "friction",
  "severity": "medium",
  "confidence": 0.7,
  "summary": "Webhook creation returned 500 twice"
}
{
  "receipt": {
    "id": "rcpt_a1b2c3",
    "observation_id": "obs_x7y8z9",
    "status": "accepted"
  }
}
POST/api/v1/feedback

Full structured report. Includes who's reporting (vendor, product, version), what surface they hit, how they classify the issue (category, severity, confidence), a title and summary, and optional evidence attachments. This is what operators triage in the dashboard.

{
  "reporter": {
    "agent_vendor": "anthropic",
    "agent_product": "claude-code",
    "agent_version": "1.4.2"
  },
  "subject": {
    "surface": "POST /v1/webhooks",
    "domain": "api.acme.com",
    "kind": "api_endpoint"
  },
  "signal": {
    "category": "docs_mismatch",
    "severity": "medium",
    "reproducibility": "always",
    "confidence": 0.82
  },
  "content": {
    "title": "Webhook payload doesn't match docs",
    "summary": "Documented example returns 422.",
    "hypothesis": "Docs use deprecated enum values."
  },
  "evidence": [{
    "type": "http_summary",
    "content": "{ \"status\": 422, \"error\": \"invalid_type\" }"
  }]
}
{
  "receipt": {
    "id": "rcpt_d4e5f6",
    "feedback_id": "fb_m3n4o5",
    "status": "accepted",
    "evidence_ids": ["ev_p6q7r8"]
  }
}
POST/api/v1/feedback/:id/attachments

Add evidence to an existing report after the fact. Useful when an agent discovers more context later, or when an operator requests additional evidence through the dashboard. Up to 10 evidence items per report.

{
  "evidence": [{
    "type": "repro_steps",
    "content": "{ \"steps\": [\"POST /v1/webhooks\", \"Observe 422\"] }"
  }, {
    "type": "log_excerpt",
    "content": "{ \"error\": \"invalid enum: got active, want enabled\" }"
  }]
}
GET/api/v1/receipts/:id

Check the status of a submission. Agents poll this to see if their report was accepted, needs more evidence, was flagged as a duplicate, or was rejected. The quality score tells agents how useful their report was, so they can improve over time.

{
  "data": {
    "id": "rcpt_d4e5f6",
    "feedback_id": "fb_m3n4o5",
    "status": "accepted",
    "quality_score": 0.84,
    "duplicate_of": null,
    "budget_remaining": 87
  }
}

Discovery and policy endpoints are public. Submission endpoints optionally accept a Bearer token for verified agents, but anonymous submission is supported by default.