# Feedback API

> Report a problem or a missing feature to the Checkbox team.

| Operation | Endpoint |
|---|---|
| [Send feedback](#createFeedback) | `POST /v1/feedback` |

## The Feedback object

Feedback sent to the Checkbox team.

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the feedback (fb_…). |
| `object` | enum | String representing the object's type. Always "feedback". |
| `type` | enum | Kind of feedback. One of `bug`, `idea`, `question`. |
| `status` | enum | open until Checkbox staff reply or close it. One of `open`, `replied`, `closed`. |
| `created` | integer | When it was received. Unix timestamp in seconds. |

## Send feedback {#createFeedback}

`POST /v1/feedback`

Report a problem or a missing feature in Checkbox. Include what you tried, what happened and what you expected, and the site / request id when there is one. The Checkbox team reads every message. Rate limited to 20 per key per hour.

**Scope** `account:read` · **Idempotent** (send `Idempotency-Key`) · **Operation** `createFeedback`

SDK: `checkbox.feedbacks.create()` (Node) · `checkbox.feedbacks.create()` (Python). MCP / agents: operation `createFeedback`.

#### Body

| Field | Type | Description |
|---|---|---|
| `type` | enum | bug: something is broken; idea: a missing feature or improvement; question: something unclear. Default idea. One of `bug`, `idea`, `question`. |
| `message` **required** | string | What you tried, what happened and what you expected (at most 5000 characters). |
| `context` | object | Optional context that helps us reproduce it. |
| `context.site` | string | Site id the feedback is about. |
| `context.request_id` | string | Request-Id of the API call it is about. |
| `context.tool` | string | MCP tool or CLI command involved. |
| `context.agent` | string | The agent or client sending it. |

#### Returns

Returns a [Feedback](https://checkbox.site/docs/api/feedback#the-feedback-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/feedback \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "verify_task returned needs_review for signup.consent.affirmative although the checkbox is unchecked by default."
}'
```
```node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const feedback = await checkbox.feedbacks.create({
  message: 'verify_task returned needs_review for signup.consent.affirmative although the checkbox is unchecked by default.',
});
console.log(feedback);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

feedback = checkbox.feedbacks.create(
    message="verify_task returned needs_review for signup.consent.affirmative although the checkbox is unchecked by default.",
)
print(feedback)
```

```json title="Response"
{
  "id": "fb_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "feedback",
  "type": "bug",
  "status": "open",
  "created": 1793318400
}
```