Feedback API

The feedback API sends reports about Squasher itself to the Squasher team for review. A report does not go to your project, and the API has no operations to list or read reports back. See Send feedback to Squasher for the dashboard and CLI.

Send feedback with an API key

POST https://api.squasher.ai/v1/feedback (feedback.submit) accepts the normal API key in the x-squasher-key header or the Authorization: Bearer header, or an OAuth token. A key that has only the events:ingest scope (the key inside your app) returns 403; use another key or the anonymous endpoints below.

curl -X POST https://api.squasher.ai/v1/feedback \
  -H "x-squasher-key: $SQUASHER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "kind": "docs",
    "message": "The on-call page does not explain what happens when an override ends.",
    "context": { "page": "https://docs.squasher.ai/features/on-call", "client": "claude-code" }
  }'

Field	Limit
`message`	Required. 1–4,000 characters.
`kind`	`bug`, `idea`, `docs`, or `other`. The default is `other`.
`title`	At most 256 characters. The default is the first line of the message.
`context.page`	The dashboard URL, docs URL, or path that the report is about. 2,048 characters.
`context.tool`	The MCP operation, CLI command, or API endpoint. 256 characters.
`context.client`	The agent or client name, for example `claude-code`. 128 characters.

Unknown fields return 400. The body can be at most 32 KiB; a larger body returns 413. A successful request returns 201:

{
  "receipt": {
    "id": "0c5f7a52-3f0e-4b8e-9d0a-2b7c4f1e6a10",
    "feedback_id": "5d1e2c3b-7a8f-4c6d-9e0b-1f2a3b4c5d6e",
    "status": "accepted",
    "created_at": "2026-09-29T12:00:00.000Z"
  }
}

Squasher records the organization, project, and user that the credential belongs to, so the team can follow up. Do not put secrets, personal data, or telemetry payloads in a report. Each organization can send 100 reports an hour. A request over the limit returns 429 with a Retry-After header. The TypeScript client has client.feedback.submit(params). It sends each report once and does not retry by itself. Over MCP, call the operation in execute:

return await squasher.request({
  method: "POST",
  path: "/v1/feedback",
  body: {
    kind: "bug",
    message: "errors.list returned issues from another environment.",
    context: { tool: "errors.list", client: "claude-code" },
  },
});

feedback.submit is a write operation, so it is not available in a read-only MCP session.

Send feedback without an API key

Squasher implements the six public Feedback.now operations. An agent can report a problem with an API, documentation page, CLI command, or SDK method without an API key or project ID. Reports go to the Squasher team. Fetch the discovery document and policy before constructing a submission:

Operation	Endpoint
Discover capabilities	`GET https://squasher.ai/.well-known/agent-feedback.json`
Read validation policy	`GET https://squasher.ai/api/v1/policy`
Submit an observation	`POST https://squasher.ai/api/v1/observations`
Submit full feedback	`POST https://squasher.ai/api/v1/feedback`
Attach evidence	`POST https://squasher.ai/api/v1/feedback/{id}/attachments`
Read a receipt	`GET https://squasher.ai/api/v1/receipts/{id}`

The generated contract is available at https://squasher.ai/api/openapi. Unknown object fields, invalid enum values, non-finite confidence values, and strings outside the published bounds are rejected before anything is stored.

Submit a full report

curl -X POST https://squasher.ai/api/v1/feedback \
  -H "Content-Type: application/json" \
  --data '{
    "reporter": {
      "agent_vendor": "Example",
      "agent_product": "Example Agent",
      "agent_version": "1.0"
    },
    "subject": {
      "surface": "/v1/projects",
      "domain": "api.squasher.ai",
      "kind": "api_endpoint"
    },
    "signal": {
      "category": "docs_mismatch",
      "severity": "medium",
      "reproducibility": "always",
      "confidence": 0.95
    },
    "content": {
      "title": "Documented response differs from the API",
      "summary": "The response omitted a field described by the public contract."
    }
  }'

A successful submission returns 201 and a durable receipt containing id, feedback_id, status, evidence_ids, and created_at. Poll GET /api/v1/receipts/{id} with the receipt ID. The receipt shows the result of the team’s review: accepted, duplicate, or rejected. The receipt never names other reports. It also shows the quality score and the evidence count when they are available. An observation requires surface, domain, agent_vendor, and agent_product. A full report requires reporter, subject, signal, and content; see the OpenAPI document for the nested schema. Categories are bug, docs_mismatch, friction, feature_gap, quality_degradation, and other. Each full report can hold at most 10 evidence items. Every item needs a type and nonempty content; UTF-8 content is limited to 256 KiB per item. The encoded request body is limited to about 3 MiB. The attachment endpoint accepts one evidence item, an array of items, or { "evidence": [...] }. Only the sender of a report can add evidence to it: send the request from the same network, or with the same API key or sign-in that sent a POST /v1/feedback report. Other callers get 404. Supported types are http_summary, stderr_excerpt, repro_steps, screenshot, log_excerpt, and other. Anonymous observations and full reports share a durable limit of 100 submissions per source per rolling hour. Successful submission responses include RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A limited request returns 429 plus Retry-After. Validation, missing-resource, size-limit, rate-limit, and server failures use JSON with stable error and human-readable message fields. The protocol has submission, evidence attachment, and receipt reads only. It has no list, update, or delete operations. The TypeScript client supports anonymous use without an API key:

const squasher = new SquasherClient({ baseUrl: "https://squasher.ai" });
const policy = await squasher.feedback.getProtocolPolicy();
const result = await squasher.feedback.submitObservation({
  surface: "/api/openapi",
  domain: "squasher.ai",
  agent_vendor: "Example",
  agent_product: "Example Agent",
  category: "docs_mismatch",
  confidence: 0.9,
  summary: "The generated schema did not match the observed response.",
});

Equivalent CLI commands live under squasher feedback now:

squasher feedback now discovery
squasher feedback now policy
squasher feedback now observe --body-file observation.json
squasher feedback now submit --body-file feedback.json
squasher feedback now attach "$FEEDBACK_ID" --body-file evidence.json
squasher feedback now receipt "$RECEIPT_ID"

Start here

Resources

Send feedback with an API key

Send feedback without an API key

Submit a full report

​Send feedback with an API key

​Send feedback without an API key

​Submit a full report

Send feedback with an API key

Send feedback without an API key

Submit a full report