Skip to content
Hayonix

API reference · Serverless

Roll back: a new release with an earlier release's worker spec

POST/v1/serverless/endpoints/{endpoint_id}/rollback
API keyserverless_endpoint:updateProjectIdempotency-Key
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes 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_idstringrequired

    ID of the endpoint

    ID with prefix sep_

Body

JSON (application/json): RollbackServerlessEndpointRequest.

  • release_idstringrequired

    ID of the release

    ID with prefix srl_

Response

201 ServerlessRelease — The new release

  • objectstringrequired

    Always `serverless_release`: the type of this object

    One ofserverless_release

  • idstringrequired

    Unique ID (`srl_…`)

    ID with prefix srl_

  • endpoint_idstringrequired

    ID of the endpoint

    ID with prefix sep_

  • versionintegerrequired

    Release 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 ofrolling_outactivesuperseded

  • sourcestringrequired

    What 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 ofcreatedupdatedrollback

  • based_on_release_idstring | nullrequired

    ID of the based on release

  • imagestringrequired

    Container image reference

  • registry_credential_idstring | nullrequired

    ID of the registry credential

  • commandarray of stringrequired

    Entrypoint override; empty: the image's own

  • argsarray of stringrequired

    Arguments override; empty: the image's own

  • Environment variables; secrets appear only as references

  • skusarray of stringrequired

    Acceptable hardware in order of preference

  • gpu_countintegerrequired

    Number of GPUs

  • concurrencyintegerrequired

    Jobs or HTTP requests one worker takes at once

  • disk_bytesintegerrequired

    Limit 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

    Show 1 field of models
    • reference_idstringrequired

      A 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 | nullrequired

    HTTP endpoints: where the container serves (null for queue)

    Show 2 fields of http
    • portintegerrequired

      The port the container serves HTTP on

    • health_pathstringrequired

      Path 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

    Show 3 fields of volumes
    • volume_idstringrequired

      ID of the volume

      ID with prefix vol_

    • mount_pathstringrequired

      Where every worker sees the volume

    • read_onlybooleanrequired

      Workers cannot write to it

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • completed_atstring (date-time) | nullrequired

    When no worker of an older release remained

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
409conflict_errorThe resource's current state does not allow this.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.