> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent feedback

> Report a wrong response, a docs mismatch or a missing feature to the paperplane team in one request, from REST or MCP.

Agent feedback lets an agent or a developer tell us a paperplane response was wrong, a docs page or tool description misled them, or a missing feature blocks the task. It is one request, it works over REST and MCP, and the reports go to the paperplane team. Nothing is published.

## When to report

Report a response that is wrong, incomplete or different from the documentation, an error you did not expect, or a missing feature that blocks the task. Send **one report per problem**.

Do not report errors you can fix by changing the request. A `validation_error` that names a field is the API doing its job; fix the field.

Do not use feedback to ask for help with a letter. Reports are read by people, not in real time, and a letter that is stuck is a different job: poll [`get_letter_status`](/docs/guides/mcp#the-tools) and see [Cancel & track](/docs/guides/cancel-track).

## What to send

`POST https://sendpaperplane.com/v1/feedback` with these fields:

| Field | Required | Description |
| - | - | - |
| `category` | Yes | `bug`, `docs_mismatch`, `friction`, `feature_gap`, `quality_degradation`, or `other`. |
| `note` | Yes | What went wrong and what you expected, up to 4,000 characters. |
| `order_id` | One of `order_id`, `url`, `surface` | The order the report is about, such as `ord_1a2b3c4d5e6f7a8b`. |
| `url` | One of `order_id`, `url`, `surface` | The page the report is about, such as a docs page. Query strings and fragments are dropped. |
| `surface` | One of `order_id`, `url`, `surface` | The endpoint or tool the report is about, such as `POST /v1/orders` or `send_letter`. |

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://sendpaperplane.com/v1/feedback \
    -H 'Content-Type: application/json' \
    -d '{
      "category": "docs_mismatch",
      "note": "The quote response lists a tracking line for first_class when tracking is false. The docs say tracking is only itemised when requested.",
      "surface": "POST /v1/quotes"
    }'
  ```

  ```python python theme={null}
  import requests

  requests.post(
      "https://sendpaperplane.com/v1/feedback",
      json={
          "category": "bug",
          "note": "get_letter_status returned mailed for an order the docs say is still screening.",
          "order_id": "ord_1a2b3c4d5e6f7a8b",
      },
  )
  ```
</CodeGroup>

With an `order_id` we can look at the exact order. We record it without checking it, so a mistyped id never makes a report fail, and nothing in the response tells you whether an order exists.

## From MCP

The same report is the `submit_feedback` tool on the [MCP server](/docs/guides/mcp). It takes the same fields and returns the same `feedback_id`.

```
submit_feedback(
  category="docs_mismatch",
  note="send_letter's description says the token lasts 30 minutes; mine expired at 15.",
  surface="send_letter"
)
```

It is not a read and not a spend: it records one private report, mails nothing and charges nothing. It needs no scope, so a key minted with `mail:quote` only, a key with no scopes at all, and an anonymous caller can all report.

## Response and limits

```json theme={null}
{ "status": "ok", "feedback_id": "fbk_a1b2c3d4e5f6", "already_submitted": false }
```

Reporting the same thing again from the same caller returns the original `feedback_id` with `already_submitted: true` instead of creating a duplicate. A new report returns `201`; a repeat returns `200`.

Feedback has its own rate limit of **10 reports a minute per caller** (API key, else IP), separate from every other route, so an integration that is being throttled elsewhere can still report it. A throttled report is `429 rate_limited` with a `Retry-After` header.

## What we do with the note

The note is written by whoever called the API, and an agent may be relaying text it read on a page it did not write. We treat it that way: it is stored as plain text, never rendered as HTML and never handed to a model as instructions.

Keep API keys, tokens and personal data out of the note. Strings shaped like paperplane API keys, capability and confirmation tokens, credit codes, bearer headers and payment payloads are replaced with `[redacted]` before storage, but nothing can redact a person's name or address. Describe what happened without pasting a recipient or letter text.

## Tell your agent

Add a line like this to your agent's instructions file, such as `AGENTS.md` or `CLAUDE.md`:

```
If a paperplane response is wrong or differs from the docs, report it once with POST https://sendpaperplane.com/v1/feedback (or the submit_feedback MCP tool). Include the affected order_id when there is one and never include secrets or recipient details.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.