Changelog
Legacy paths kept for compatibility, retired-endpoint replacements, and migration differences for the public API
2026-11-12
This update reorganizes the public API documentation: pages are now grouped by account, API key, usage, task, billing, and pricing, and we added docs for the key lifecycle (create, update, revoke, rotate), key balance, and model pricing.
The 5 pages under the old Account group were removed, and their doc URLs redirect to the corresponding new pages. This change only restructures the docs. Live API behavior is unchanged.
Legacy paths kept for compatibility
The following 10 legacy GET paths still work and behave exactly like the new paths on the right. They are kept only for compatibility, will be removed in a later release, and should be migrated as soon as possible. Use the new paths for all new integrations.
Note that /api/v1/account and /api/v1/account/balance are themselves new paths and are not listed here.
| Legacy path | New path |
|---|---|
/api/v1/account/api-keys | /api/v1/api-keys |
/api/v1/account/api-keys/{api_key_id} | /api/v1/api-keys/{api_key_id} |
/api/v1/account/usage/records | /api/v1/usage/records |
/api/v1/account/usage/summary | /api/v1/usage/summary |
/api/v1/account/tasks | /api/v1/tasks |
/api/v1/account/tasks/{task_id} | /api/v1/tasks/{task_id} |
/api/v1/account/billing/topups | /api/v1/billing/topups |
/api/v1/account/billing/topups/{trade_no} | /api/v1/billing/topups/{trade_no} |
/api/v1/account/billing/payment-method | /api/v1/billing/payment-method |
/api/v1/account/billing/auto-topup | /api/v1/billing/auto-topup |
Key create, update, revoke, rotate, key balance, Webhook, pricing, and Stripe invoices only ever existed as flat new paths; there are no legacy /account-prefixed paths for them.
Migrate earlier account endpoints
The table below maps old endpoints to their new equivalents. It is not a list of drop-in compatible paths. Credentials, parameters, and response formats differ, so update your client code accordingly. The old balance and create endpoints authenticated with a model key.
The new endpoints use a system access token. The old usage endpoint also required the X-User-Id header, which the new endpoint does not need.
| Earlier endpoint | New endpoint | Migration conditions |
|---|---|---|
GET /v1/balance, /balance | GET /api/v1/api-keys/{api_key_id}/balance | Use a system access token and key ID, rather than authenticating as the queried key. Unlimited remaining amounts use null instead of -1. |
GET /api/usage/tokens/requests | GET /api/v1/usage/records | Migrate parameters and fields as shown below. Cache-read and cache-write counts are returned inside usage. |
GET /api/usage/tokens/summary | GET /api/v1/usage/summary?group_by=api_key | Explicitly use group_by=api_key. record_count counts log rows, not complete requests or final net spend. |
GET /v1/user/balance, /user/balance | GET /api/v1/account/balance | Reads your account balance or subaccount budget. Decimal strings explicitly separate USD and credits. |
GET /v1/pricing | GET /api/v1/pricing?api_key_id={api_key_id} | Use api_key_id for a key context. after/next_after become cursor/next_cursor. The response uses code/message/data; it is not the same protocol. |
POST /v1/tokens | POST /api/v1/api-keys | Follow the new request fields and types. group, cross_group_retry, and Webhook configuration are not accepted, so this does not replace every legacy capability. |
The old allow_ips newline-separated string becomes a string array, for example ["192.0.2.10","2001:db8::1"]. Both create and update accept it: [] clears the restriction, while null or invalid addresses return 400. Only single IP addresses are supported.
CIDR ranges are not.
Usage fields and pagination
Time parameters change from Unix-second start_timestamp/end_timestamp to timezone-aware from/to, kept consistent across pages. token_id becomes the api_key_id string and page_size becomes limit. Old cursors cannot be reused.
For cache fields: old cache_tokens maps to usage.cache_read_tokens and cache_creation_tokens to usage.cache_write_tokens. The new API also reports 5-minute and 1-hour write breakdowns, which are already included in cache_write_tokens and must not be added again.
Missing or invalid values return null. An explicitly recorded zero returns 0.
Parameter errors now return HTTP 400 (instead of 422) with a numeric code. The old quota field used an internal unit, while the new recorded_credits is already in credits, so migrate the amount semantics rather than just renaming the field.
| Earlier field | New field | Change |
|---|---|---|
log_id | id | Rename only. |
token_id | api_key_id | Numeric ID passed as a string. |
token_name | key_name | Rename only. |
model_name | model | Rename only. |
start_timestamp/end_timestamp | from/to | Unix seconds → timezone-aware RFC 3339; keep the same range across pages. |
page_size | limit | Items per page. |
cost_usd | recorded_cost_usd | Recorded USD cost of the log line, decimal string. |
quota | recorded_credits | Internal quota units → converted credits; do not reuse old values. |
prompt_tokens | usage.input_tokens | Moved into the usage object. |
completion_tokens | usage.output_tokens | Moved into the usage object. |
reported_total_tokens | usage.reported_total_tokens | Total tokens reported upstream; moved into usage. |
cache_tokens | usage.cache_read_tokens | Cache-read tokens; moved into usage. |
cache_creation_tokens | usage.cache_write_tokens | Total cache-write tokens, already including the 5-minute and 1-hour breakdowns; do not add them again. |
request_count | record_count | Number of log entries, not complete requests. |
data[] | data.items[] | Record array moved to data.items. |
meta.has_more | data.has_more | Pagination info moved into data. |
meta.next_cursor | data.next_cursor | Page cursor; old cursors do not work with the new endpoint. |
Key creation field changes
| Old field | New field | Change |
|---|---|---|
expired_time | expires_at | Unix seconds (-1 = never) becomes timezone-aware RFC 3339; null or omitted = never expires. |
remain_quota/remain_credits | remaining_credits | Decimal string preserving precision. |
daily_credits/monthly_credits | daily_limit_credits/monthly_limit_credits | null or "0" = no limit. |
unlimited_quota | unlimited | Boolean; null rejected. When true, remaining_credits must be omitted or null. |
model_limits_enabled | — | Removed; a non-empty model_limits array enables the restriction. |
model_limits | model_limits | Comma-separated string → string array; up to 1024 UTF-8 bytes when joined. |
allow_ips | allow_ips | Newline-separated string → string array; single IPs only, no CIDR; [] clears, null/invalid returns 400. |
Behavior changes: a successful create returns HTTP 201 instead of 200, and the full secret is returned in data.key including the sk- prefix.
Capabilities that remain distinct
The account task endpoint only returns task status and billing metadata. It does not replace generation-result queries. See Actual cost and task usage for the meaning of billing and usage.
The pricing catalog only reflects current rates and cannot recompute historical bills. The public API key lifecycle also does not support changing quotas or restoring revoked keys.
Webhooks are managed through a dedicated configuration endpoint: each ordinary model key has one configuration, managed separately from key creation and update. See Get Webhook configuration.