Skip to content
Hayonix

API reference · Dedicated endpoints

Set the share of requests each deployment receives (weights sum to 100)

PUT/v1/endpoints/{dedicated_endpoint_id}/traffic
API keydedicated_endpoint:updateProject
TypeScript
client.dedicatedEndpoints.setTrafficSplit()
Python
client.dedicated_endpoints.set_traffic_split()
CLI
hayonix endpoints traffic

Replaces the whole split: listed deployments get their weight and every other deployment of the endpoint gets 0. Takes effect for new requests at once; each deployment's autoscaler follows its share of the demand.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the dedicated_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 -X PUT "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/traffic" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "deployments": [
    {
      "deployment_id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "weight": 50
    },
    {
      "deployment_id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e5",
      "weight": 50
    }
  ]
}'

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.

Path parameters

  • dedicated_endpoint_idstringrequired

    ID of the dedicated endpoint

    ID with prefix ded_

Body

JSON (application/json): EndpointTrafficSplitRequest.

  • deploymentsarray of objectrequired

    Each deployment of the endpoint at most once; deployments not listed get weight 0

    1–4 items

    Show 2 fields of deployments
    • deployment_idstringrequired

      ID of the deployment

      ID with prefix dpl_

    • weightintegerrequired

      Percentage of requests this deployment receives (0–100)

      0–100

Response

200 JSON — The deployments with their new weights

  • The items

    Show 19 fields of data
    • objectstringrequired

      Always `endpoint_deployment`: the type of this object

      One ofendpoint_deployment

    • idstringrequired

      Unique ID (`dpl_…`)

      ID with prefix dpl_

    • endpoint_idstringrequired

      ID of the endpoint

      ID with prefix ded_

    • namestringrequired

      Its name

    • statusstringrequired

      `ready`: at least min_replicas ready. `degraded`: some, fewer. `failed`: stopped starting replicas after repeated failures (see last_failure); update or restart to retry.

      One ofstoppedstartingreadydegradedfailed

    • modelobjectrequired

      Model ID (`publisher/name`)

      Show 6 fields of model
      • catalog_model_idstring | nullrequired

        ID of the catalog model

      • repositorystringrequired

        Where the weights come from: a Hugging Face repository `<owner>/<name>`, or a `fine-tuned://` URI for a fine-tuned model

      • filestring | nullrequired

        The weights file or quantisation tag chosen in the repository; null when the whole repository is used

      • revisionstring | nullrequired

        Branch, tag or commit; null for the repository's default branch

      • token_secret_idstring | nullrequired

        ID of the token secret

      • fine_tuned_model_idstring | nullrequired

        Set when the deployment serves a fine-tuned model (then `repository` is its `fine-tuned://` URI)

    • engineServingEnginerequired

      `llama_cpp`: GGUF chat and completion models (CPU or GPU). `tei`: embedding and rerank models. `vllm`: chat, completion and embedding models on GPUs.

      One ofllama_cppteivllm

    • hardwareobjectrequired

      The hardware each replica runs on and its GPUs per replica

      Show 2 fields of hardware
      • skustringrequired

        Hardware type code

      • gpu_countintegerrequired

        Number of GPUs

    • regionstringrequired

      Region code

    • engine_optionsobjectrequired

      Engine settings chosen for this deployment

      Show 2 fields of engine_options
      • context_lengthinteger | nullrequired

        Context length in tokens per request; null: the engine's default

      • parallelinteger | nullrequired

        Requests one replica runs at once; null: the engine's default

    • disk_gbintegerrequired

      Disk per replica for the weights, in GB

    • min_replicasintegerrequired

      Fewest replicas kept running while the endpoint runs

    • max_replicasintegerrequired

      Most replicas the autoscaler may run

    • autoscalingobjectrequired

      How the replica count follows demand

      Show 1 field of autoscaling
      • target_concurrencyintegerrequired

        Concurrent requests per replica the autoscaler aims for: replicas = ceil(concurrency / target), between min and max

    • traffic_weightintegerrequired

      Percentage of the endpoint's requests sent to this deployment (0–100; the weights of an endpoint's deployments sum to 100)

    • replicasReplicaCountsrequired
      Show 4 fields of replicas
      • readyintegerrequired

        Replicas taking traffic

      • startingintegerrequired

        Replicas downloading weights or loading the model

      • unhealthyintegerrequired

        Replicas that were ready but are failing health checks (no traffic)

      • drainingintegerrequired

        Replicas finishing their requests before removal

    • last_failurestring | nullrequired

      Why the most recent replica failed to start; null when there is none. Cleared on a start of the endpoint or an update of the deployment.

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • updated_atstring (date-time)required

      When it last changed (ISO 8601, UTC)

  • next_cursorstring | nullrequired

    Pass as `cursor` to get the next page; null when there is no more

Example response
Example response
{
  "data": [
    {
      "object": "endpoint_deployment",
      "id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "endpoint_id": "ded_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "name": "string",
      "status": "stopped",
      "model": {
        "catalog_model_id": "string",
        "repository": "string",
        "file": "string",
        "revision": "string",
        "token_secret_id": "string",
        "fine_tuned_model_id": "string"
      },
      "engine": "llama_cpp",
      "hardware": {
        "sku": "string",
        "gpu_count": 1
      },
      "region": "string",
      "engine_options": {
        "context_length": 1,
        "parallel": 1
      },
      "disk_gb": 1,
      "min_replicas": 1,
      "max_replicas": 1,
      "autoscaling": {
        "target_concurrency": 1
      },
      "traffic_weight": 1,
      "replicas": {
        "ready": 1,
        "starting": 1,
        "unhealthy": 1,
        "draining": 1
      },
      "last_failure": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "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.
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.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.