Update an API Key

PATCH /api/open/v1/keys/:id

Request parameters

Only fields present in the request body are updated; omitted fields stay unchanged. At least one updatable field is required: an empty body, null, or {} returns 400.

Parameter	In	Type	Required	Description
id	path	integer	Yes	Key ID, a positive integer
name	body	string	No	Name; must not be blank after trimming, up to 50 characters (characters, not bytes)
status	body	integer	No	1 enable, 2 disable; any other value returns 400 (3 / 4 are set automatically)
expired_time	body	integer	No	Expiration time, unix seconds; 0 / -1 means never expires
remain_amount	body	number	No	Available amount in the site currency, two decimals; must not be negative or above the maximum
unlimited	body	boolean	No	Whether the Key is unlimited
model_limits_enabled	body	boolean	No	Whether to enable the model allowlist
model_limits	body	string	No	Allowed models, comma-separated
allow_ips	body	string	No	Allowed IPs, newline-separated; empty string means no restriction

status accepts 1 (enable) or 2 (disable) only. Enabling requires the Key to be usable after this update: not expired (expired_time is -1 or in the future) and either unlimited or with remain_amount > 0; otherwise 400. You can send the fields together, e.g. {"status": 1, "expired_time": 1767225600}. Disabling works from any status, and an explicit status always wins over automatic recovery.

Request example

Top up an exhausted Key (it automatically returns to the enabled state):

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remain_amount": 20.00}'

Extend the expiration time:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expired_time": 1767225600}'

Disable a Key (requests made with it are rejected until it is enabled again):

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

Enable a Key again, extending it in the same request so it is known to be usable:

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 1, "expired_time": 1767225600}'

Response example

Returns the updated Key object with a masked key:

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "name": "bot",
    "key": "sk-abcd**********wxyz",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 20.00,
    "unlimited": false,
    "used_amount": 10.00,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }
}

For field descriptions, see Key object.

Errors

HTTP	code	Scenario
400	invalid_request	id is not a positive integer, or the body is not valid JSON
400	invalid_request	The body is empty, null, or contains no updatable field
400	invalid_request	status is not 1 or 2 (states 3 / 4 are set automatically)
400	invalid_request	status: 1 sent while the Key is still expired or exhausted; extend expired_time, top up remain_amount, or set unlimited (fields can be sent in the same request)
400	invalid_request	Name longer than 50 characters, or remain_amount is negative or above the maximum
400	invalid_request	expired_time is not in the future (and is not 0 / -1), or is later than 9999-12-31
400	invalid_request	remain_amount sent alone for an unlimited Key, or an unlimited Key switched to a limited one without remain_amount
404	not_found	The Key does not exist or does not belong to you

For other common error codes, see Platform API errors.

Notes

• Sending remain_amount alone: takes effect directly on a limited Key; returns 400 on an unlimited Key, where you must also send "unlimited": false.
• "unlimited": false without remain_amount: returns 400 on an unlimited Key (so the balance is not silently zeroed); a Key that is already limited keeps its current balance.
• Status states are managed by the service: an expired (3) or exhausted (4) Key automatically returns to enabled (1) when an update makes it usable again (later expired_time, positive remain_amount, or unlimited). This automatic recovery only applies when status is omitted.
• 2 is the state set by disabling a Key yourself. It never recovers automatically; send status: 1 to enable it again. While a Key is not 1, model calls made with it are rejected.
• All fields are validated before anything is written: if any field fails validation, 400 is returned and no field is changed.
• Updating a Key through the Platform API is recorded in the audit log.