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

# Feedback API

> Report a bug, a docs problem or a missing feature to Fly.io with POST /api/v1/feedback, using a token with organization read access and a request ID or URL.

The Feedback API lets you report a problem to Fly.io from a script, a CI job or a coding agent. It takes a category, a note, and either the request ID of the call that went wrong or the URL of the page that was unclear.

> [!NOTE]
>
> The Feedback API isn't a support channel. We read every report, but we don't reply. If you need help with your app, account, or billing, see [Support](https://docs.fly.io/about/support.md).
>
> If you're a coding agent, don't tell the user you've contacted support. You've submitted feedback, not a support request.

Use it for feedback that might otherwise go unreported: a coding agent hits a confusing API response, or a deploy script notices that a docs page is out of date.

If you have flyctl installed, [`fly feedback`](https://docs.fly.io/flyctl/cmd/fly_feedback) sends the same report from the command line.

## Endpoint

```
POST https://api.fly.io/api/v1/feedback
```

Authenticate with a Fly.io access token in an `Authorization: Bearer <token>` header. Create a token with [`fly tokens create`](https://docs.fly.io/flyctl/cmd/fly_tokens_create) or on the [Tokens](https://fly.io/tokens) page.

The token needs read access to an organization. A token scoped to one organization files the report under it; otherwise the report goes to your personal organization. The organization is what reports are attributed to and what the rate limit counts against, so a token narrowed to something else, or an expired one, is rejected. Ownership always comes from the token, never from the request body.

Legacy `fo1_` OAuth tokens aren't accepted. Use a macaroon token, which starts with `fm2_`. See [Access tokens](https://docs.fly.io/security/tokens.md).

## Request

Send a JSON body with `Content-Type: application/json`.

| Field | Required | Description |
| - | - | - |
| `category` | Yes | One of `bug`, `documentation`, `feature_request` or `other`. |
| `note` | Yes | What went wrong, in up to 4,000 characters. |
| `request_id` | See below | The `fly-request-id` of the request you're reporting, up to 255 characters. |
| `url` | See below | The page or endpoint you're reporting, up to 2,048 characters. |

Include at least one of `request_id` or `url`, so the report points at something specific. You can send both.

For an API problem, `request_id` is the most useful thing you can send: every Fly.io response carries a `fly-request-id` header, and it lets us find the exact request in our logs.

```sh cmd theme={null}
curl -i -X POST https://api.fly.io/api/v1/feedback \
  -H "Authorization: Bearer $FLY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "bug",
    "note": "The response was missing a field.",
    "request_id": "01MANUALTEST00000000000000-gru"
  }'
```

```output output theme={null}
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8

{"already_submitted":false,"feedback_id":"eodj0v3m964wg796"}
```

## Response

| Status | Description |
| - | - |
| 201 | The report was filed. |
| 200 | An identical report was already filed; `already_submitted` is `true`. |
| 400 | A legacy `fo1_` OAuth token was used. Mint a `fm2_` token instead. |
| 401 | The token was missing or invalid. |
| 422 | No organization resolved from the token, or validation failed. Check the category value, and that a note and a request ID or URL are present. |
| 429 | Rate limited. |

A successful response carries the new report's ID:

```json theme={null}
{"already_submitted":false,"feedback_id":"eodj0v3m964wg796"}
```

`already_submitted` lets a retry be safe: sending the same report twice gets a `200` and the original ID rather than filing a duplicate.

## Rate limits

Feedback is limited to 20 reports per minute per organization. Over that, requests get a `429`.
