Access
Use the public API to read your account data and manage your ordinary model keys. Main accounts do not inherit access to subaccount data. Administrators can also access only their own resources.
Use the public API to read your account data and manage your ordinary model keys. Main accounts do not inherit access to subaccount data. Administrators can also access only their own resources.
Use https://api.toapis.com internationally or https://api.toapis.cn in mainland China. These are the API origins; do not send these requests to the website root domain.
Get a system access token
Sign in to Account settings and generate a System Access Token. Regenerating it invalidates the previous token, so update existing integrations.
Every request carries Bearer YOUR_SYSTEM_ACCESS_TOKEN in the Authorization header. Send exactly one Authorization header. Model API keys (sk-...), cookies, URL credentials, and Agent/MCP tokens are not accepted as identity, and X-User-Id is not needed.
Note that a system access token can perform key and user file writes. It is not a read-only credential.
The optional X-Locale header accepts en, zh, zh-TW, ja, ko, ru. Without a valid value, the account language preference and negotiation result apply. A request does not initialize the account preference.
Judge results by the HTTP status and numeric code, not by the localized message.
curl https://api.toapis.com/api/v1/account \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'Responses and amounts
Every response has only three top-level fields: code, message, data. On success code=0 and message="". The HTTP status is 200 for normal success, 201 when creating a key, and 202 when a Webhook test is queued or a file deletion request is accepted.
On failure the real HTTP status is preserved, and error data only contains param, params, request_id, or null without exposing internal details.
Resource IDs and amounts are decimal strings. api_key_id in Webhook endpoints is an integer. Times are RFC 3339 with timezone, and unknown or inapplicable values return null per each field’s contract.
Balances and usage report both USD and credits, converted with the credits_per_usd value in the response. Payment amounts keep their original currency.
Every response includes Cache-Control: private, no-store and X-Request-Id headers. X-Request-Id identifies this API request; it is not the original generation request ID recorded in usage trace.
{
"code": 0,
"message": "",
"data": {
"items": [],
"has_more": false,
"next_cursor": null,
"meta": {}
}
}Pagination and time ranges
Except for the user file list, lists return data.items, has_more, next_cursor, and meta. An empty list has items as [] and the last page has next_cursor as null. No total count is returned. To page forward, pass next_cursor back unchanged as cursor while keeping the same filters.
After changing filters, start over from the first page.
Time ranges use UTC half-open intervals [from, to), with second-resolution boundaries rounded up. Defaults and limits differ per endpoint: usage requires from and to on every page with a 31-day maximum. Tasks default to the last 24 hours, up to 31 days.
Top-ups and invoices default to the last 31 days, up to 366 days. A default window is fixed on the first page, so later pages may omit it. Unknown or duplicated parameters and bad escaping return 400.
Ranges use UTC half-open intervals [from,to). Second-resolution boundaries round upward. Usage requires both from and to on every page, with a 31-day maximum. Tasks default to 24 hours with a 31-day maximum. Top-ups and invoices default to 31 days with a 366-day maximum.
Default ranges freeze on the first page and can stay omitted on subsequent pages. Unknown parameters, repeated scalars, and malformed escapes return 400.
Rate limits and errors
Reads share a limit of 120 requests per user per minute. Usage summaries, invoices, and pricing each have an additional limit of 6 requests per minute; invoice lists and details share the invoice limit.
API key, Webhook, and user file writes share a separate limit of 10 requests per user per minute and do not consume the read allowance. Regenerating a system access token does not reset limits. Canonical and compatibility paths share the corresponding allowance.
Excessive request frequency or concurrency can return 429. Back off using Retry-After plus random jitter. A 503 response means the service is temporarily unavailable; reduce the request rate before retrying. Do not blindly resend timed-out create, rotate, or deletion requests.
| HTTP | code | Action |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | Correct the body, parameters, or cursor. |
| 401 | 11032 / 11059 | Check the system access token. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | Check account status, resource permissions, and key group. |
| 404 | 13001 / 16008 | The resource is missing or belongs to another account. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | Resolve key count, expiry, quota, or billing mapping conditions. |
| 429 | 10002 | Back off according to Retry-After. |
| 500 | 10000 / 13029 | Keep request_id for investigation. |
| 503 | 11001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029 | Back off; narrow the usage range if needed. |
Data scope
A main account only sees its own data. Member (subaccount) data is not included, and subaccounts cannot read billing. Usage records are live snapshots of consumption logs that change with later settlement and refunds, so they do not equal final net spend.
Task endpoints return persisted task metadata and confirmable billing only: no generation results, no upstream polling, no settlement, and no refunds.
Top-ups exclude manually granted credits and standalone offline refunds, and invoices only cover the currently verified Stripe Customer.
Use the numeric id from key lists or details as the resource ID. The secret string (sk-...) cannot be used. The full secret is returned only once, in create and rotate responses, and is never returned by later reads.
A successful write means the settings are saved; they may take a short time to take effect.
Disabling, rotating, or revoking a key can fail in-flight requests or tasks: the platform does not automatically cancel tasks or issue refunds, and there is no overlap window where old and new secrets are both valid.
Endpoints
Use the canonical paths below. See Changelog for the legacy /api/v1/account/... GET paths kept for compatibility and migration from earlier endpoints.
User file endpoints manage registered files, user retention, and asynchronous deletion requests. File-list pagination is an exception: it returns only items and next_cursor, with "" on the last page and no has_more or meta. Accepted deletion requests return HTTP 202. Retention updates and deletion requests share the account write budget. User retention requires platform automatic cleanup to be enabled; manual deletion does not. See the user file endpoints below for scope and examples.
| HTTP | |
|---|---|
GET /api/v1/account | Get account profile |
GET /api/v1/account/balance | Get account balance |
GET /api/v1/api-keys | List API keys |
GET /api/v1/api-keys/{api_key_id} | Get API key |
GET /api/v1/api-keys/{api_key_id}/balance | Get key balance |
POST /api/v1/api-keys | Create an API key |
PATCH /api/v1/api-keys/{api_key_id} | Update an API key |
DELETE /api/v1/api-keys/{api_key_id} | Revoke an API key |
POST /api/v1/api-keys/{api_key_id}/rotate | Rotate an API key |
GET /api/v1/webhook | Get Webhook configuration |
PATCH /api/v1/webhook | Update Webhook configuration |
POST /api/v1/webhook/rotate-secret | Rotate Webhook signing secret |
POST /api/v1/webhook/test | Test Webhook |
GET /api/v1/webhook/events | List Webhook events |
GET /api/v1/webhook/events/{event_id} | Get Webhook event |
GET /api/v1/usage/records | List usage records |
GET /api/v1/usage/summary | Get usage summary |
GET /api/v1/tasks | List account tasks |
GET /api/v1/tasks/{task_id} | Get account task |
GET /api/v1/billing/topups | List top-up orders |
GET /api/v1/billing/topups/{trade_no} | Get top-up order |
GET /api/v1/billing/payment-method | Get payment method |
GET /api/v1/billing/auto-topup | Get auto top-up configuration |
GET /api/v1/billing/stripe/invoices | List invoices |
GET /api/v1/billing/stripe/invoices/{invoice_id} | Get invoice |
GET /api/v1/pricing | Get model pricing |
GET /api/v1/user/file | List user files |
GET /api/v1/user/file/retention | Get file retention |
PUT /api/v1/user/file/retention | Set file retention |
POST /api/v1/user/file/deletion-requests | Create a file deletion request |
GET /api/v1/user/file/deletion-requests/{id} | Get file deletion progress |
Webhook
Setup order:
- Call
POST /api/v1/webhook/rotate-secretto generate the signing secret and save it on the receiver. - Call
PATCH /api/v1/webhookto set the callback URL and enable delivery. - Call
POST /api/v1/webhook/testto send a test event, or query the event list to confirm delivery.
See Get Webhook configuration for the full steps and signature verification.