Source: https://ailoot.ai/docs/en/cabinet/redeem/
Canonical: https://ailoot.ai/docs/en/cabinet/redeem/
Language: en

[Dashboard API](https://ailoot.ai/docs/en/) 

# Top-up codes

[Markdown](https://ailoot.ai/docs/en/cabinet/redeem/index.md)

Methods, request fields, and responses.

This section contains 2 methods. Open a method to view access requirements, request fields, and the response.

| Method and path | Description | Access |
| --- | --- | --- |
| `POST /api/v1/redeem` | Redeem a code | Dashboard token |
| `GET /api/v1/redeem/history` | Redemption history | Dashboard token |

**POST /api/v1/redeem** — Redeem a code

Access: Dashboard token

POST`/api/v1/redeem`

## JSON / form fields

| The field | Type | Required | Validation / description |
| --- | --- | --- | --- |
| `code` | `string` | yes | required |

Request body template

```json
{
  "code": "PLACEHOLDER_CODE (string)"
}
```

PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays.

Request schema: `RedeemRequest`

## Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: `RedeemCode`. See the Data schemas pages for fields and types.

Response schema with illustrative values

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "code": "PLACEHOLDER_CODE (string)",
    "type": "PLACEHOLDER_TYPE (string)",
    "value": "PLACEHOLDER_VALUE (number)",
    "status": "PLACEHOLDER_STATUS (string)",
    "used_by": "PLACEHOLDER_USED_BY (integer)",
    "used_at": "PLACEHOLDER_USED_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "validity_days": "PLACEHOLDER_VALIDITY_DAYS (integer)",
    "notes": "PLACEHOLDER_NOTES (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}
```

Note: all personal data and objects are scoped to the JWT subject.

Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed.

This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request.

**GET /api/v1/redeem/history** — Redemption history

Access: Dashboard token

GET`/api/v1/redeem/history`

Read operation; use an ID from your previous response

```bash
curl --fail-with-body "https://ailoot.ai/api/v1/redeem/history" \
  -H "Authorization: Bearer $TOKEN"
```

## Query parameters

| The field | Type | Required | Validation / description |
| --- | --- | --- | --- |
| `page` | `integer` | no | ; default: 1; positive integer |
| `page_size` | `integer` | no | ; default: 20; positive; clamp to100 |

No request body is required. Send the parameters listed above in the URL.

## Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: `RedeemCode`. See the Data schemas pages for fields and types.

Response schema with illustrative values

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "code": "PLACEHOLDER_CODE (string)",
        "type": "PLACEHOLDER_TYPE (string)",
        "value": "PLACEHOLDER_VALUE (number)",
        "status": "PLACEHOLDER_STATUS (string)",
        "used_by": "PLACEHOLDER_USED_BY (integer)",
        "used_at": "PLACEHOLDER_USED_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "validity_days": "PLACEHOLDER_VALIDITY_DAYS (integer)",
        "notes": "PLACEHOLDER_NOTES (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}
```

Note: all personal data and objects are scoped to the JWT subject.

Still have questions? Send your Request ID and a description — we'll help you troubleshoot.[Contact support](mailto:support@ailoot.ai)

## Ailoot · The company and its project portfolio





Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control.





The company and its project portfolio: millions of customers; monthly sales in the billions.





Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.