> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.to/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.to/_mcp/server.

# Agent Feedback

> Report an API issue or documentation mismatch straight from your integration, quoting the request id of the call it is about

If something in the API or these docs does not behave the way you expected, tell us from the integration itself. This endpoint exists for the AI agent driving our API on your behalf as much as for you: when it hits a wrong response, a missing field, or a docs page that does not match reality, it can file the report in the same code path.

## Request ids

Every response from the API carries an `X-Request-Id` header, and every error body repeats it as a top-level `request_id`. Include it in your feedback and we can find the exact call on our side.

```json
{
  "detail": "Phone number with ID 'ext:agent_42' not found",
  "error": {
    "message": "Phone number with ID 'ext:agent_42' not found",
    "code": "PHONE_NUMBER_NOT_FOUND",
    "type": "not_found"
  },
  "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91"
}
```

## Submit feedback

```http
POST /v1/feedback
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "category": "bug",
  "note": "GET /v1/numbers?externalId= returns 200 with an empty list; expected 404 or 422.",
  "request_id": "3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91",
  "url": "https://docs.agentphone.ai/phone-numbers",
  "tags": ["production", "team-alpha"]
}
```

| Field        | Required | Description                                                                                          |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `category`   | yes      | One of `bug`, `docs_mismatch`, `friction`, `feature_gap`, `quality_degradation`, `other`             |
| `note`       | yes      | What went wrong and what you expected instead. 1 to 4000 characters                                  |
| `request_id` | no       | The `request_id` of the call the feedback is about, from the `X-Request-Id` header or the error body |
| `url`        | no       | The page the feedback is about, such as a docs page. `http(s)` only, up to 2048 characters           |
| `tags`       | no       | Up to 20 labels of 1 to 50 characters each, for your own filtering                                   |

### Response

`201 Created` when the feedback is stored:

```json
{
  "feedback_id": "cmuh5cajt0002qvc7rtcy7ohn",
  "already_submitted": false,
  "request_id": "b9bec613-44ed-4ee5-9d5b-3a87da5f8efe"
}
```

Feedback is stored once per `request_id` on your account. Sending the same `request_id` again returns `200 OK` with the original `feedback_id` and `already_submitted: true`, so a retrying agent never files duplicates. Feedback without a `request_id` is always stored.

The `request_id` in the response is the id of the feedback call itself, not the one you reported.

## Example

```python
import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.get("https://api.agentphone.ai/v1/numbers/ext:agent_42", headers=headers)
if r.status_code == 404:
    requests.post(
        "https://api.agentphone.ai/v1/feedback",
        headers=headers,
        json={
            "category": "bug",
            "note": "Tagged this number as agent_42 five seconds ago; lookup by ext: still 404s.",
            "request_id": r.headers["X-Request-Id"],
        },
    )
```

## What happens next

Every report is emailed to the founders the moment it is stored. Reports that quote a `request_id` are matched to the call's logs, so a one-line note is usually enough. The endpoint is limited to 30 submissions a minute per account.