Reference

Agent Feedback

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.

{
  "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

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"]
}
FieldRequiredDescription
categoryyesOne of bug, docs_mismatch, friction, feature_gap, quality_degradation, other
noteyesWhat went wrong and what you expected instead. 1 to 4000 characters
request_idnoThe request_id of the call the feedback is about, from the X-Request-Id header or the error body
urlnoThe page the feedback is about, such as a docs page. http(s) only, up to 2048 characters
tagsnoUp to 20 labels of 1 to 50 characters each, for your own filtering

Response

201 Created when the feedback is stored:

{
  "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

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.