API keys

Methods, request fields, and responses.

Full guide

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

Method and path	Description	Access
`GET /api/v1/keys`	List API keys	Dashboard token
`POST /api/v1/keys`	Create an API key	Dashboard token
`DELETE /api/v1/keys/:id`	Delete an API key	Dashboard token
`GET /api/v1/keys/:id`	Get an API key by ID	Dashboard token
`PUT /api/v1/keys/:id`	Update an API key	Dashboard token

GET /api/v1/keys — List API keys

Access: Dashboard token

GET/api/v1/keys

Read operation; use an ID from your previous response

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

Query parameters

The field	Type	Required	Validation / description
`sort_by`	`string`	no	; default: created_at
`sort_order`	`string`	no	; default: desc
`search`	`string`	no
`status`	`string`	no
`page`	`integer`	no	; default: 1; positive; page_size/limit <=1000
`page_size`	`integer`	no	; default: 20; positive; page_size/limit <=1000
`limit`	`integer`	no	; default: 20; positive; page_size/limit <=1000

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: APIKey. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (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.

Note: the response contains the secret key field. Do not publish real values.

POST /api/v1/keys — Create an API key

Access: Dashboard token

POST/api/v1/keys

JSON / form fields

The field	Type	Required	Validation / description
`name`	`string`	yes	required
`custom_key`	`string`	no	; Optional custom key value; may be null
`ip_whitelist`	`array`	no	; IP allowlist
`ip_blacklist`	`array`	no	; IP blocklist
`quota`	`number`	no	; Key spending limit in USD; may be null
`expires_in_days`	`integer`	no	; Validity period in days; may be null
`rate_limit_5h`	`number`	no	; may be null
`rate_limit_1d`	`number`	no	; may be null
`rate_limit_7d`	`number`	no	; may be null

Request body template

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

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: CreateAPIKeyRequest

Response

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

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

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (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.

Note: Idempotency-Key is supported. A repeated request returns the saved response with X-Idempotency-Replayed.

Note: the response contains the secret key field. Do not publish real values.

DELETE /api/v1/keys/:id — Delete an API key

Access: Dashboard token

DELETE/api/v1/keys/:id

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

No request body is required.

Response

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

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

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.

Note: the response contains the secret key field. Do not publish real values.

GET /api/v1/keys/:id — Get an API key by ID

Access: Dashboard token

GET/api/v1/keys/:id

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

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: APIKey. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

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

Note: the response contains the secret key field. Do not publish real values.

PUT /api/v1/keys/:id — Update an API key

Access: Dashboard token

PUT/api/v1/keys/:id

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

JSON / form fields

The field	Type	Required	Validation / description
`name`	`string`	no
`status`	`string`	no	omitempty,oneof=active inactive
`ip_whitelist`	`array`	no	; Allowed IPs: null leaves the list unchanged; an empty array clears it; may be null
`ip_blacklist`	`array`	no	; Blocked IPs: null leaves the list unchanged; an empty array clears it; may be null
`quota`	`number`	no	; Key spending limit in USD; 0 means unlimited; may be null
`expires_at`	`string`	no	; Expiry time in ISO 8601 format; may be null
`reset_quota`	`boolean`	no	; Reset the amount used against the spending limit; may be null
`rate_limit_5h`	`number`	no	; may be null
`rate_limit_1d`	`number`	no	; may be null
`rate_limit_7d`	`number`	no	; may be null
`reset_rate_limit_usage`	`boolean`	no	; Reset usage for spending-window limits; may be null

Request body template

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

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: UpdateAPIKeyRequest

Response

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

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

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (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.

Note: the response contains the secret key field. Do not publish real values.

Note: while the key has unfinished requests with reserves, its spending limit cannot be reduced or reset. Send only the fields you want to change.

Still have questions? Send your Request ID and a description — we'll help you troubleshoot.Contact support