API reference · Serverless
Roll back: a new release with an earlier release's worker spec
/v1/serverless/endpoints/{endpoint_id}/rollback- TypeScript
client.serverless.rollbackEndpoint()- Python
client.serverless.rollback_endpoint()- CLI
hayonix serverless rollback
Creates the next release with the chosen release's spec (version numbers only grow) and rolls workers over to it like any update. The secrets and credentials it references must still exist; rolling back to the current release is a conflict.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_endpoint:update permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/rollback" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"release_id": "srl_01jc5zq4m8k3v6x9t2w7r0b1e4"
}'Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Path parameters
endpoint_idstringrequiredID of the endpoint
ID with prefix sep_
Body
JSON (application/json): RollbackServerlessEndpointRequest.
release_idstringrequiredID of the release
ID with prefix srl_
Response
201 ServerlessRelease — The new release
objectstringrequiredAlways `serverless_release`: the type of this object
One of
serverless_releaseidstringrequiredUnique ID (`srl_…`)
ID with prefix srl_
endpoint_idstringrequiredID of the endpoint
ID with prefix sep_
versionintegerrequiredRelease number within the endpoint: 1, 2, 3… (never reused)
statusstringrequired`rolling_out`: the current release while workers of older releases remain. `active`: the current release, every worker runs it. `superseded`: a newer release replaced it.
One of
rolling_outactivesupersededsourcestringrequiredWhat made the release: `created` (the endpoint was created), `updated` (an update changed the worker spec) or `rollback` (a copy of `based_on_release_id`)
One of
createdupdatedrollbackbased_on_release_idstring | nullrequiredID of the based on release
imagestringrequiredContainer image reference
registry_credential_idstring | nullrequiredID of the registry credential
commandarray of stringrequiredEntrypoint override; empty: the image's own
argsarray of stringrequiredArguments override; empty: the image's own
Environment variables; secrets appear only as references
skusarray of stringrequiredAcceptable hardware in order of preference
gpu_countintegerrequiredNumber of GPUs
concurrencyintegerrequiredJobs or HTTP requests one worker takes at once
disk_bytesintegerrequiredLimit on each worker's writable disk, in bytes (0: no limit beyond the host's)
Models the worker mounts from the host’s model cache
ShowHide 1 field of
modelsreference_idstringrequiredA model reference of this project (POST /v1/model-references). Its files are cached on the host and mounted read-only at /model-cache/models--<owner>--<name> before the worker starts; HF_HUB_CACHE points there unless env sets it.
ID with prefix mrf_
httpobject | nullrequiredHTTP endpoints: where the container serves (null for queue)
ShowHide 2 fields of
httpportintegerrequiredThe port the container serves HTTP on
health_pathstringrequiredPath probed (GET; 2xx or 3xx is healthy) before a worker takes requests
Network volumes mounted into every worker; workers run on the host they are pinned to
ShowHide 3 fields of
volumesvolume_idstringrequiredID of the volume
ID with prefix vol_
mount_pathstringrequiredWhere every worker sees the volume
read_onlybooleanrequiredWorkers cannot write to it
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
completed_atstring (date-time) | nullrequiredWhen no worker of an older release remained
Example response
{
"object": "serverless_release",
"id": "srl_01jc5zq4m8k3v6x9t2w7r0b1e4",
"endpoint_id": "sep_01jc5zq4m8k3v6x9t2w7r0b1e4",
"version": 1,
"status": "rolling_out",
"source": "created",
"based_on_release_id": "string",
"image": "string",
"registry_credential_id": "string",
"command": [
"string"
],
"args": [
"string"
],
"env": [
{
"name": "string",
"value": "string"
}
],
"skus": [
"string"
],
"gpu_count": 1,
"concurrency": 1,
"disk_bytes": 1,
"models": [
{
"reference_id": "mrf_01jc5zq4m8k3v6x9t2w7r0b1e4"
}
],
"http": {
"port": 1,
"health_path": "string"
},
"volumes": [
{
"volume_id": "vol_01jc5zq4m8k3v6x9t2w7r0b1e4",
"mount_path": "string",
"read_only": true
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |