Feedback
When the API, an MCP tool, or these docs get in your way, tell us. Your integration or AI agent can report a confusing error, wrong or missing docs, or a capability it needs, right from the moment it gets stuck. We read every report, and once we've fixed the API or the docs, we mark it resolved so your agent knows when to try again.
Connected over MCP? The same endpoints are available as the submit_feedback, list_feedback, and get_feedback tools, and the server tells your agent when to use them.
The feedback model
- Name
id- Type
- string
- Description
- Stable public UUID.
- Name
category- Type
- string
- Description
- Required. One of
bug(the API behaved differently from its documentation),documentation(docs or a tool description are wrong, missing, or unclear),unclear_error(an error didn't explain how to recover),missing_feature(the API can't do what you need), orother.
- Name
summary- Type
- string
- Description
- Required. One sentence describing the problem, up to 200 characters.
- Name
details- Type
- string
- Description
- Required, up to 5,000 characters. What you tried, what happened, and what you expected.
- Name
operation- Type
- string | null
- Description
- Optional, up to 200 characters. The endpoint or MCP tool involved, such as
POST /api/v1/calls/{id}/transfersorstart_call_transfer.
- Name
request_id- Type
- string | null
- Description
- Optional, up to 100 characters. The
X-Request-Idresponse header of a failing request, so we can find it in our logs.
- Name
status- Type
- string
- Description
openuntil we've dealt with it.resolvedmeans we fixed the API or the docs, so try again.closedmeans we closed it without a change, for example because it duplicates another report or the API already works as intended.
- Name
created_at- Type
- string
- Description
- ISO 8601 timestamp of the report.
- Name
closed_at- Type
- string | null
- Description
- When the report was resolved or closed.
nullwhile open.
Leave API keys, tokens, and personal data such as caller phone numbers out of reports. We don't need them to fix the problem.
Reports belong to the account. Any API key or OAuth token for the account can list and read them. Tokens issued to company-owned applications can't use these endpoints and receive 403. API and MCP submissions share a limit of 20 reports per account per hour; after that, submitting returns 429 with a Retry-After header.
The list can also include technical reports from your AI receptionist. These contain fixed problem codes and tool names, not caller words or contact details. Their call association stays internal and is not returned by the API or sent to Linear. Receptionist reports have a separate limit of 20 per account per hour and do not use your API submission allowance.
List feedback
Returns the account's 100 most recent reports, newest first. Check here before retrying something you reported.
Request
curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{"feedback":[{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"}]}
Submit feedback
Send category, summary, and details, plus operation and request_id when you have them. Submit once per problem, after trying the documented approach. Returns the report with status 201. Invalid or missing fields return 422.
Request
curl https://app.phone.inc/api/v1/feedback -H "X-Api-Key: $PHONE_INC_API_KEY" -H 'Content-Type: application/json' -d '{"category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c"}'
Response
{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"open","created_at":"2026-11-09T14:03:12.481920Z","closed_at":null}
Retrieve feedback
Returns one report and its current status. Reports from other accounts return 404.
Request
curl "https://app.phone.inc/api/v1/feedback/$FEEDBACK_ID" -H "X-Api-Key: $PHONE_INC_API_KEY"
Response
{"id":"019daef1-085e-7000-aaaa-000000000009","category":"unclear_error","operation":"POST /api/v1/calls/{id}/transfers","summary":"The 422 does not say which field is wrong","details":"Sent employee_id and got an empty errors object. Expected the response to name the missing field.","request_id":"5c1f2a7e-9b3d-4e8a-a1c2-3f4d5e6a7b8c","status":"resolved","created_at":"2026-11-09T14:03:12.481920Z","closed_at":"2026-11-10T09:41:05.120334Z"}