Top-up codes

Methods, request fields, and responses.

Full guide

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

{
  "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

{
  "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.

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

Access: Dashboard token

GET/api/v1/redeem/history

Read operation; use an ID from your previous response

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

{
  "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