---
title: "Report a problem as an AI agent"
method: POST
path: "/feedback"
tags: ["Agent feedback"]
---

# Report a problem as an AI agent

`POST /feedback`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/feedback`
- Auth: one of:
  - none
  - HTTP bearer

Agent Feedback Protocol v0.1 (https://trybackloop.com/spec/). Report anything that prevented or complicated a task on Cavuno's API, CLI, MCP server or SDK. Responses use the protocol's own shapes, not the usual error envelope. Bodies over 16384 bytes and unknown fields are rejected. 20 reports per account or visitor every 5 minutes. Never include credentials or personal data; send the report, then continue with your task. Discovery: `/.well-known/agent-feedback`.

## Request body

- AgentFeedbackReport
  - `type` 'missing_capability' | 'bug' | 'unclear_documentation' | 'unexpected_response' | 'unhelpful_error' | 'performance' | 'other', required: The kind of problem.
  - `goal` string, required: What you or your user were trying to accomplish, in plain language.
  - `message` string, required: What prevented or complicated the task.
  - `endpoint` string: API path, CLI command or MCP tool involved, e.g. `/jobs`.
  - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS': HTTP method, when `endpoint` is a path.
  - `outcome` 'blocked' | 'degraded' | 'completed': `blocked`: the task failed. `degraded`: it finished worse or slower. `completed`: a suggestion only.
  - `workaround` boolean: Whether you found a workaround.
  - `workaround_description` string: The workaround, if any.
  - `expected` string: What you expected to find or happen.
  - `suggestion` string: A concrete change that would have let you succeed.
  - `request_id` string: The `X-Request-Id` of the failing call, if you have it.
  - `session_id` string: Reuse one value for every report in a task; a retry with the same content returns the original report.
  - `agent` object: Who is reporting: name (agent or product) and model.
    - `name` string
    - `version` string
    - `model` string
    - `framework` string
  - `evidence` object: Sanitized details of the failing call, with no credentials or personal data.
    - `status_code` integer
    - `request` object
    - `response_excerpt` string
  - `metadata` object: Any other context, as a JSON object.
  - `spec_version` '0.1': Protocol version. Only `0.1` is accepted.

## Response `202`

Accepted. A retry with the same `session_id` and content returns the original report.

- AgentFeedbackAccepted
  - `id` string, required: The report id, e.g. `fb_…`.
  - `status` 'accepted', required
  - `received_at` string, required: When Cavuno first received this report (ISO 8601). A retry returns the original time.

## Other responses

- `400`: `invalid_json` or `invalid_feedback`.
- `413`: `payload_too_large`.
- `415`: `unsupported_media_type`.
- `429`: `rate_limited`. Wait for `Retry-After` seconds.
- `503`: `rate_limit_unavailable`. Continue with your task.

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)