> For the complete documentation index, see [llms.txt](https://docs.nansen.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nansen.ai/api/feedback.md).

# Feedback

Report bugs, missing capabilities and other API friction directly from your account, CLI or agent, and track the result with a durable receipt.

This reports friction with the Nansen API itself — a bug, a missing capability, confusing behavior — from your own authenticated account. It is separate from the page-feedback widget GitBook shows at the bottom of each documentation page, which goes to the docs team, not API engineering.

## Submit a report

```
POST /api/v1/feedback
```

Requires [authentication](https://docs.nansen.ai/getting-started/authentication.md). Free — it never costs credits, and submitting one never requires a paid plan. Every call needs an `Idempotency-Key` header (1–128 ASCII letters, digits, underscores or hyphens) so a retried network call doesn't create a second report. Reuse the same key only to retry the same report; a reused key with different `category`, `description`, or other report content returns `409`. Comparison ignores `client` (attribution only) and treats `request_ids` as an unordered set, so changing only those does not trigger a conflict.

| Field                                     | Required | Notes                                                                                     |
| ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `category`                                | Yes      | One of `bug`, `data_quality`, `documentation`, `missing_capability`, `usability`, `other` |
| `description`                             | Yes      | What happened and what was needed, up to 2,000 characters                                 |
| `endpoint`                                | No       | The API endpoint path involved                                                            |
| `tool`                                    | No       | The tool name involved, for MCP/agent clients                                             |
| `goal`                                    | No       | What you were trying to achieve                                                           |
| `expected_behavior` / `observed_behavior` | No       | Up to 2,000 characters each                                                               |
| `workaround`                              | No       | Any workaround used                                                                       |
| `request_ids`                             | No       | Up to 10 of your own request IDs, as evidence                                             |
| `client`                                  | No       | `{"name": ..., "version": ...}`, attribution only                                         |

The request body is capped at 16 KiB. Do not include credentials, full conversations or raw API responses — text that looks like an API key, bearer token, JWT or similar is rejected before the report is saved.

### Example: accepted

```json
POST /api/v1/feedback
Idempotency-Key: 7d0cfa19-5e6b-49d4-a71c-5f75a07d780e

{
  "category": "missing_capability",
  "description": "I need to compare labels across 50 wallets, but could not find a bulk lookup.",
  "goal": "Compare labels across a wallet list."
}
```

```json
201 Created
Location: /api/v1/feedback/fb_01JA8Z6K2R7N4Q9V3T5W8X1Y2Z

{
  "feedback_id": "fb_01JA8Z6K2R7N4Q9V3T5W8X1Y2Z",
  "submission_id": "7d0cfa19-5e6b-49d4-a71c-5f75a07d780e",
  "status": "received",
  "disposition": null,
  "received_at": "2026-10-13T12:00:00Z",
  "updated_at": "2026-10-13T12:00:00Z",
  "expires_at": "2027-10-13T12:00:00Z",
  "replayed": false,
  "quota": {"limit": 7, "remaining": 6, "resets_at": "2026-10-19T00:00:00Z"}
}
```

### Example: replay

Retrying the same `Idempotency-Key` with the same report returns the existing receipt instead of creating a new one:

```json
200 OK

{
  "feedback_id": "fb_01JA8Z6K2R7N4Q9V3T5W8X1Y2Z",
  "submission_id": "7d0cfa19-5e6b-49d4-a71c-5f75a07d780e",
  "status": "reviewed",
  "disposition": null,
  "received_at": "2026-10-13T12:00:00Z",
  "updated_at": "2026-10-14T08:15:00Z",
  "expires_at": "2027-10-13T12:00:00Z",
  "replayed": true,
  "quota": {"limit": 7, "remaining": 0, "resets_at": "2026-10-19T00:00:00Z"}
}
```

The same key with a **different** report returns `409 conflict` (`idempotency_key_reused`) instead. If Nansen erased the report early, for example because it contained personal data, the same key returns `409 conflict` with reason `feedback_erased`. Stop retrying that key and discard its local retry data; send the report again only as a deliberate new report with a new key. If a request times out or the connection drops before you see a response, retry the unchanged report with the unchanged key — never rotate the key to "try again," since that creates a second report and spends a second slot of your weekly allowance.

### Example: weekly allowance reached

```json
429 Too Many Requests
Retry-After: 475200

{
  "error": "Too Many Requests",
  "message": "Seven reports have been accepted for this account this week.",
  "code": "rate_limit_exceeded",
  "status": 429,
  "request_id": "req_attempt_8",
  "doc_url": "https://docs.nansen.ai/getting-started/error-handling#rate_limit_exceeded",
  "reason": "feedback_weekly_quota_exhausted",
  "retry_after": 475200,
  "quota": {"limit": 7, "remaining": 0, "resets_at": "2026-10-19T00:00:00Z"}
}
```

### Example: feedback is not enabled for this account

```json
403 Forbidden

{
  "error": "Forbidden",
  "message": "Feedback is not enabled for this account.",
  "code": "forbidden",
  "status": 403,
  "request_id": "req_attempt_11",
  "doc_url": "https://docs.nansen.ai/getting-started/error-handling#forbidden",
  "reason": "feedback_not_enabled"
}
```

Stop automatic retries and keep the submission ID. There is no timed retry hint. Never switch accounts or use payment to bypass rollout. Existing accepted-ID replays and receipt reads remain available after access is removed. A saved automatic-reporting preference does not grant rollout access.

A storage incident still returns `503` with reason `feedback_store_unavailable` and a retry hint. Its outcome can be unknown. Retry the same key and unchanged report without assuming that it was never saved.

## Read a receipt

```
GET /api/v1/feedback/{feedback_id}
```

Free, and always reflects the current review state. An unknown, expired, or other account's ID all return a uniform `404` — the response never reveals whether an ID belongs to someone else.

| `status`   | Meaning                                                                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `received` | Saved. No promise of a timeline.                                                                                                               |
| `reviewed` | A teammate triaged it. Still no promise of a fix or a date.                                                                                    |
| `closed`   | Review is complete. `disposition` is set: `resolved`, `duplicate`, or `not_planned`. A `duplicate` disposition never reveals the other report. |

Receipts and retry protection (the `Idempotency-Key` replay behavior above) are accessible for **one year** from acceptance, recorded as `expires_at`. After that, the receipt stops returning and the same key is treated as a new submission. An early erasure removes the receipt at once, and the key keeps returning `feedback_erased` until the original `expires_at`.

## Automatic-reporting preference

```
GET /api/v1/feedback/preferences
PUT /api/v1/feedback/preferences
```

One preference per account, controlling whether an AI agent or client may send a feedback report **on its own initiative**, without asking first:

```json
{
  "automatic_reporting": "disabled",
  "configured": false,
  "version": 0,
  "updated_at": null,
  "can_manage": true
}
```

* `automatic_reporting` is `enabled` or `disabled`. An account that has never chosen is `disabled` (`configured: false`).
* This only governs an agent initiating a report by itself. A report you explicitly ask for or approve does not require an enabled automatic-reporting preference. Account rollout, permissions, quota and host approval controls still apply.
* Changing it needs an API key with the `account` permission, or a signed-in CLI/browser session (`PUT`). Reading it (`GET`) is open to the same credentials that may submit feedback, including an OAuth connector grant — a connector may read the preference but not change it.
* `PUT` requires `expected_version` set to the `version` you last read. A stale version returns `409` with the current value and stores nothing — show that current value and ask again before changing it; don't silently retry your original change against the newer version. A `503` on a write carries `write_outcome`: `"unknown"` means the write may have committed — read the preference back before retrying, and retry only with the original value and version.

To change it in the Nansen app, open the [API page](https://app.nansen.ai/api?tab=api) and use the **Automatic feedback** card. MCP clients that expose `get_feedback_preferences` can read it with an empty `request`. The tool does not change the preference. Check your installed CLI version's help for available commands, or use this endpoint directly.

## Who can call this

| Caller                                        | Submit / read receipts | Read preference | Change preference                  |
| --------------------------------------------- | ---------------------- | --------------- | ---------------------------------- |
| API key (any scope)                           | Yes                    | Yes             | Yes, with the `account` permission |
| Nansen CLI browser login                      | Yes                    | Yes             | Yes                                |
| OAuth connector grant (ChatGPT, Claude, etc.) | Yes                    | Yes             | No                                 |
| Telegram bot user, own linked account         | Yes                    | Yes             | No                                 |
| x402 or other pay-per-request identity        | No                     | No              | No                                 |
| Shared service/sample-workflow identity       | No                     | No              | No                                 |

A connector grant is otherwise restricted to read-only data access; feedback is the one exception, because the account behind it is still a verified customer with something to report. It needs no new OAuth scope and no reauthorization — the same `nansen:read` grant you already approved in [ChatGPT](https://docs.nansen.ai/mcp/connectors/chatgpt.md), [Claude](https://docs.nansen.ai/mcp/connectors/claude.md), [Grok](https://docs.nansen.ai/mcp/connectors/grok.md) or [Muse](https://docs.nansen.ai/mcp/connectors/muse.md) covers it, carried over the same trusted connector-to-backend path that already handles your other tool calls. The MCP server offers `get_feedback_preferences`, `submit_feedback` and `get_feedback`. Each client must expose these tools in its own catalog before you can call them. A valid grant alone does not establish tool availability or submission eligibility. All three operations cost zero credits.

Every allowed caller is attributed to the same verified account, so a weekly allowance, receipts and the automatic-reporting preference are shared across your API key, CLI login, connector grant and Telegram link — not tracked separately per credential.

## Privacy

Don't include credentials, full conversations, or raw API responses in a report; recognizable credential material is rejected before anything is saved. Nansen staff see report content to triage it. Receipts (and the retry protection tied to them) stop being accessible one year after acceptance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nansen.ai/api/feedback.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
