# Feedback: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/feedback
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 1.

## POST /v1/feedback

Operation id: `send_feedback`

**Send a thumbs up or thumbs down**

Records whether a result was good. `request_id` is the id of the request you are rating, as a UUID (the part of an `X-Request-ID` header after `req_`); `feedback` is `thumbs_up` or `thumbs_down`; `feedback_text` is an optional comment of at most 4096 characters. You can rate only a request your own account made: an id that was never issued, or that belongs to another account, is 404 `not_found` (the record of a request is written just after its answer is sent, so rate it a moment later, not in the same instant). Sending the same rating twice stores it twice.

Every problem with the body, including text that is not valid JSON, is 400 `invalid_request`; the message names the field. Only an over-long comment has its own code, `feedback_text_too_long`. If the rating could not be stored the reply is 503 `db_unavailable`; send it again.

Access: API key required; free and paid accounts. Cost: no token cost.

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `request_id` | string | The id of the request you are rating, as a UUID. |
| `feedback` | "thumbs_up" \| "thumbs_down" | Your verdict. |
| `feedback_text` | string | An optional comment, at most 4096 characters. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `success` | true | Always true: the rating was stored. |
| `request_id` | string | The id you sent. |
| `feedback` | "thumbs_up" \| "thumbs_down" | The verdict you sent. |
| `message` | string | A short confirmation sentence that repeats the verdict and the comment. |

### Responses

200: The rating is stored.

```json
{
  "data": {
    "success": true,
    "request_id": "4e1b7c9a-2d58-4f03-8a6b-5c0d9e1f2a37",
    "feedback": "thumbs_up",
    "message": "✓ Feedback recorded: thumbs_up - Great result"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is not valid JSON, `request_id` is missing or not a UUID, `feedback` is not one of the two verdicts, or `feedback_text` is not a string (`invalid_request`); `feedback_text` is too long (`feedback_text_too_long`).

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Error: request_id must be a valid UUID",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_request"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

404: The id was not issued to your account (it never existed, or another account made it).

```json
{
  "error": {
    "code": "not_found",
    "message": "Error: request not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`feedback_text_too_long`](https://www.scarleta.ai/docs/errors#feedback_text_too_long), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`invalid_request`](https://www.scarleta.ai/docs/errors#invalid_request), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
curl -X POST "https://api.scarleta.ai/v1/feedback" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "4e1b7c9a-2d58-4f03-8a6b-5c0d9e1f2a37",
    "feedback": "thumbs_up",
    "feedback_text": "Great result"
  }'
```