Skip to content
Hayonix

API reference · Serverless

Create a serverless endpoint (the webhook secret is returned once)

POST/v1/serverless/endpoints
API keyserverless_endpoint:createProjectIdempotency-Key
TypeScript
client.serverless.createEndpoint()
Python
client.serverless.create_endpoint()
CLI
hayonix serverless create

Creates the endpoint with release 1 of its worker spec. No worker starts until there is work, unless min_workers is above 0; workers are billed per second while they run. The response carries the completion webhook signing secret, which is never shown again.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the serverless_endpoint:create 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" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "image-captioner",
  "image": "registry.example.com/team/captioner:1.0.0",
  "skus": [
    "cpu-2c-4gb"
  ],
  "max_workers": 3,
  "scaling": {
    "policy": "queue_delay",
    "target": 5
  }
}'

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.

Body

JSON (application/json): CreateServerlessEndpointRequest.

  • namestringrequired

    Its name

    1–63 characters

  • modestring

    `queue` (default): jobs through the job API, run by a handler on the worker runtime. `http`: your container serves HTTP itself and requests to the endpoint URL are routed to its workers. Fixed at creation.

    One ofqueuehttp

  • regionstring

    Region code

    1–64 characters

  • imagestringrequired

    Container image reference

    1–512 characters

  • registry_credential_idstring | null

    ID of the registry credential

    ID with prefix rcr_

  • commandarray of string

    Replaces the image's entrypoint (default: the image's own)

    up to 64 items

  • argsarray of string

    Replaces the image's default arguments (default: the image's own)

    up to 256 items

  • Environment variables of every worker. Names starting with `WORKER_RUNTIME_` are reserved for the platform.

    up to 128 items

  • skusarray of stringrequired

    Acceptable hardware in order of preference; workers take the first with capacity

    1–5 items

  • gpu_countinteger

    GPUs per worker on GPU SKUs

    0–8

  • concurrencyinteger

    Jobs (queue endpoints, 1–64) or requests (HTTP endpoints, 1–1000) one worker takes at once (default 1)

    1–1000

  • disk_bytesinteger

    Limit on each worker container's writable disk, in bytes (default 0: no limit beyond the host's)

    at least 0

  • Models from the model hub the worker reads (one revision per repository)

    up to 8 items

    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_

  • HTTP endpoints only (required for them): where the container serves

    Show 2 fields of http
    • portintegerrequired

      The port your container serves HTTP on

      1–65535

    • health_pathstring

      Path the platform probes (GET; any 2xx or 3xx is healthy) before a worker takes requests, and to take it out of rotation when it fails (default `/health`)

      pattern ^\/[A-Za-z0-9._~/?=&%-]{0,255}$

  • Network volumes of this project to mount into every worker (at most 4; default none). Volumes live on one host until shared storage exists, so every worker of the endpoint then runs on the host the volumes are pinned to, and waits for capacity there when it is full. Changing the list makes a new release.

    up to 4 items

    Show 3 fields of volumes
    • volume_idstringrequired

      ID of the volume

      ID with prefix vol_

    • mount_pathstringrequired

      Absolute path inside every worker (not a system path such as /etc or /usr)

      2–256 characters

    • read_onlyboolean

      Mount read-only (default false: workers may write)

  • min_workersinteger

    Default 0

    0–100

  • max_workersinteger

    Default 3

    0–100

  • idle_timeout_secondsinteger

    An idle worker is removed after this (default 30)

    1–3600

  • execution_timeout_secondsinteger

    Per job (default 600)

    1–86400

  • queue_ttl_secondsinteger

    A job not started within this expires (default 86400)

    10–604800

  • result_ttl_secondsinteger

    Results are kept this long after a job finishes (default 3600)

    60–604800

  • max_retriesinteger

    Re-runs after a lost worker before the job fails (default 2)

    0–10

  • Show 2 fields of scaling
    • policystringrequired

      Queue endpoints: `queue_delay` adds workers once the oldest queued job has waited `target` seconds; `requests_per_worker` keeps ceil((queued + running) / `target`) workers. HTTP endpoints: `in_flight` keeps ceil((requests in flight + waiting) / `target`) workers.

      One ofqueue_delayrequests_per_workerin_flight

    • targetinteger

      Seconds (queue_delay, default 5), jobs per worker (requests_per_worker, default 1) or requests in flight per worker (in_flight, default 1)

      1–3600

  • webhook_urlstring (uri) | null

    Default completion webhook for jobs of this endpoint

    up to 2048 characters

  • cold_start_wait_secondsinteger

    HTTP endpoints: a request that finds no ready worker waits this long for one to start or resume before it is answered 503 `no_worker_ready` (default 60)

    1–300

  • drain_timeout_secondsinteger

    HTTP endpoints: a worker leaving rotation (scale-down, new release) gets this long to finish the requests it has in flight (default 60)

    1–3600

  • Show 2 fields of fast_resume
    • max_paused_workersinteger

      Idle workers to keep paused instead of removing them, so the next request or job resumes one in a fraction of a cold start (default 0: off). Paused time is not charged.

      0–10

    • paused_keep_secondsinteger

      A worker paused this long is removed (default 600)

      30–86400

Response

201 CreatedServerlessEndpoint — The new endpoint and its first release

  • objectstringrequired

    Always `serverless_endpoint`: the type of this object

    One ofserverless_endpoint

  • idstringrequired

    Unique ID (`sep_…`)

    ID with prefix sep_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • namestringrequired

    Its name

  • statusstringrequired

    `active`: takes jobs or requests. `deleted`: deleted (deleted endpoints are not returned by the API)

    One ofactivedeleted

  • modestringrequired

    `queue`: jobs through the job API, run by a handler on the worker runtime. `http`: requests to `url` are routed to the workers, which serve HTTP themselves. Fixed at creation.

    One ofqueuehttp

  • urlstring | nullrequired

    HTTP endpoints: where to send requests (any path), with an API key of this project holding `serverless_endpoint:invoke` as `Authorization: Bearer`. Null for queue endpoints.

  • min_workersintegerrequired

    Workers kept running even without work (billed while running)

  • max_workersintegerrequired

    Most workers the autoscaler starts

  • idle_timeout_secondsintegerrequired

    Seconds an idle worker above `min_workers` stays before removal

  • execution_timeout_secondsintegerrequired

    Seconds one attempt of a job may run before it ends as `timed_out`; a job may ask for less

  • queue_ttl_secondsintegerrequired

    Seconds a job may wait in the queue before it ends as `expired`

  • result_ttl_secondsintegerrequired

    Seconds a finished job's result is kept

  • max_retriesintegerrequired

    Times a job is re-queued after its worker is lost before it fails

  • scalingobjectrequired

    How the number of workers follows demand

    Show 2 fields of scaling
    • policystringrequired

      `queue_delay`: add workers once the oldest queued job has waited `target` seconds. `requests_per_worker`: keep ceil((queued + running jobs) / `target`) workers. `in_flight` (HTTP endpoints): keep ceil((requests in flight + waiting) / `target`) workers.

      One ofqueue_delayrequests_per_workerin_flight

    • targetintegerrequired

      Seconds (`queue_delay`), jobs per worker (`requests_per_worker`) or requests in flight per worker (`in_flight`)

  • webhook_urlstring | nullrequired

    Default completion webhook for jobs of this endpoint; null for none

  • cold_start_wait_secondsintegerrequired

    HTTP endpoints: seconds a request that finds no ready worker waits for one before it is answered 503 `no_worker_ready`

  • drain_timeout_secondsintegerrequired

    HTTP endpoints: seconds a worker leaving rotation gets to finish the requests it has in flight

  • fast_resumeobjectrequired

    Idle workers kept paused (frozen, holding their memory and GPU) instead of removed. Paused time is not charged; paused workers are the first thing the platform reclaims when a host needs the capacity.

    Show 2 fields of fast_resume
    • max_paused_workersintegerrequired

      Idle workers kept paused instead of removed (0: fast resume is off)

    • paused_keep_secondsintegerrequired

      Seconds a worker stays paused before it is removed

  • current_releaseServerlessReleaserequired
    Show 21 fields of current_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

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • webhook_secretstringrequired

    Signs completion webhooks. Returned only here (and on rotation); store it now.

Example response
Example response
{
  "object": "serverless_endpoint",
  "id": "sep_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "name": "string",
  "status": "active",
  "mode": "queue",
  "url": "string",
  "min_workers": 1,
  "max_workers": 1,
  "idle_timeout_seconds": 1,
  "execution_timeout_seconds": 1,
  "queue_ttl_seconds": 1,
  "result_ttl_seconds": 1,
  "max_retries": 1,
  "scaling": {
    "policy": "queue_delay",
    "target": 1
  },
  "webhook_url": "string",
  "cold_start_wait_seconds": 1,
  "drain_timeout_seconds": 1,
  "fast_resume": {
    "max_paused_workers": 1,
    "paused_keep_seconds": 1
  },
  "current_release": {
    "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"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "webhook_secret": "string"
}

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.
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.