> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Feedback

> Tell Maple about a bug, a missing capability, wrong docs, or an error you could not act on.

When the API does something wrong, cannot do what you need, disagrees with these docs, or answers with an error that does not tell you what to change, send `POST /v1/feedback`. It is written for the coding agents that do most of the work against this API as much as for people, so an agent that hits a wall can report it in the same session instead of working around it.

```bash theme={null}
curl https://api.maple.inc/v1/feedback \
  -H "Authorization: Bearer $MAPLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "unclear_error",
    "summary": "Waitlist join answers 400 without naming the field",
    "attempted": "Add a party of four to the waitlist",
    "expected": "The error names the field that failed",
    "endpoint": "POST /v1/waitlist_entries",
    "request_ids": ["req_3f2b7c1e-9a4d-4e8b-b1c2-5d6e7f8a9b0c"]
  }'
```

| Field | Required | What to put in it |
| - | - | - |
| `kind` | Yes | `bug`, `missing_capability`, `docs_wrong`, `unclear_error`, or `other` |
| `summary` | Yes | One line, at most 200 characters |
| `attempted` | No | What you were trying to do, as a goal rather than a call; leave it out when the feedback is not about a task |
| `expected` | No | What you expected the API to do |
| `observed` | No | What it did instead |
| `endpoint` | No | The method and path, such as `POST /v1/waitlist_entries` |
| `request_ids` | No | Up to ten ids of the requests involved, usually their `x-request-id` values |

## Cite your requests

Every response carries an `x-request-id` header. Put the ids of the requests involved in `request_ids`, because they let us see the operation, status, and error code of what you actually sent. We copy those details onto the feedback when you send it, so they stay readable after request history expires at seven days. An id we cannot match to your app's requests in the same environment in the last seven days, such as one from another system, is kept as you sent it; the report is never refused over an id.

## A contract that will not break

An agent may send feedback from code written once and left running for years, so we will never make a breaking change to `POST /v1/feedback`. We may add optional fields and new `kind` values, and the response may gain fields, so ignore any you do not know. We will not remove or rename a field, change what one means, make an optional field required, add a required field, drop a `kind`, or tighten a length limit. A request that works today will keep working.

## What happens next

The API stores the report and answers `200` with a `feedback` object whose `status` is `received`. Maple reads feedback every week and decides what to change; sending it changes nothing on its own, and the API does not send a reply. Leave secrets, API keys, and guest details out of the text.

Any credential may send feedback in either environment, and no scope is required. Each app may send 20 reports per environment per hour; past that the API answers `429` with a `Retry-After` header.