API reference · Dedicated endpoints
Create a dedicated endpoint (a catalog model or your own Hugging Face model) with its first deployment
/v1/endpoints- TypeScript
client.dedicatedEndpoints.create()- Python
client.dedicated_endpoints.create()- CLI
hayonix endpoints create
Creates the endpoint, its model ID <org slug>/<name> (used as model in inference requests) and a first deployment that takes all traffic. Unless start is false it starts at once, which needs credit; replicas are billed per second at their hardware's price once ready, and requests are never charged per token.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the dedicated_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/endpoints" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "support-bot",
"model": {
"source": "huggingface",
"repository": "bartowski/SmolLM2-135M-Instruct-GGUF",
"file": "Q4_K_M",
"type": "chat"
},
"hardware": {
"sku": "cpu-2c-4gb"
},
"min_replicas": 1,
"max_replicas": 2,
"inactivity_timeout_seconds": 3600
}'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. |
Body
JSON (application/json): CreateDedicatedEndpointRequest.
namestringrequiredLowercase letters, digits and hyphens. The model ID is `<org slug>/<name>`.
1–48 characters
display_namestring | nullName to show people
1–100 characters
inactivity_timeout_secondsintegerStop after this long without a request (0: never; default 3600)
0–604800
startbooleanStart serving now (default true)
deployment_namestringName of the first deployment (default `primary`)
1–48 characters
modelstring | HuggingFaceModelSource | FineTunedModelSourcerequiredModel ID (`publisher/name`)
ShowHide 2 fields of
hardwareskustringrequiredHardware type code
1–64 characters
gpu_countintegerGPUs per replica on GPU SKUs
0–8
regionstringRegion code
1–64 characters
engineany JSONengine_optionsEngineOptionsShowHide 2 fields of
engine_optionscontext_lengthintegerContext length in tokens each request may use (default: the model's context length, else the engine's default)
128–1048576
parallelintegerRequests one replica runs at once
1–256
disk_gbintegerRoom for the weights (default 10 on CPU, 200 on GPU)
1–2000
min_replicasintegerDefault 1
1–32
max_replicasintegerDefault 1
1–32
autoscalingEndpointAutoscalingShowHide 1 field of
autoscalingtarget_concurrencyintegerrequiredConcurrent requests per replica to aim for: replicas = ceil(concurrency / target), between min and max
1–1024
Response
201 DedicatedEndpoint — The new endpoint
objectstringrequiredAlways `dedicated_endpoint`: the type of this object
One of
dedicated_endpointidstringrequiredUnique ID (`ded_…`)
ID with prefix ded_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
project_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredIts name
display_namestring | nullrequiredName to show people
modelstringrequiredThe model ID to send in OpenAI-compatible requests
typestringrequiredWhat the served model does
One of
chatcompletionembeddingrerankcontext_lengthinteger | nullrequiredContext length in tokens of the served model; null when not known
statusstringrequired`stopped`: no replicas. `stopping`: stopped, replicas still being removed. `starting`: running, but no deployment with traffic has a ready replica yet. `serving`: every deployment with traffic has at least its minimum replicas ready. `degraded`: serving, but some deployment with traffic has fewer ready replicas than its minimum (or none). `failed`: no deployment with traffic is ready and at least one has stopped starting replicas after repeated failures.
One of
stoppedstoppingstartingservingdegradedfaileddesired_statestringrequiredWhat you asked for: `running` after create (unless `start` was false) or start, `stopped` after stop or an automatic stop (see `stop_reason`)
One of
runningstoppedstop_reasonstring | nullrequired`requested`, `inactivity`, `billing:<reason>` or `deleted`
inactivity_timeout_secondsintegerrequiredThe endpoint stops after this many seconds without a request (0: never)
last_request_atstring (date-time) | nullrequiredTime last request (ISO 8601, UTC)
started_atstring (date-time) | nullrequiredWhen it started (null until then) (ISO 8601, UTC)
stopped_atstring (date-time) | nullrequiredTime stopped (ISO 8601, UTC)
The live deployments of the endpoint, oldest first
ShowHide 19 fields of
deploymentsobjectstringrequiredAlways `endpoint_deployment`: the type of this object
One of
endpoint_deploymentidstringrequiredUnique ID (`dpl_…`)
ID with prefix dpl_
endpoint_idstringrequiredID of the endpoint
ID with prefix ded_
namestringrequiredIts 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 of
stoppedstartingreadydegradedfailedmodelobjectrequiredModel ID (`publisher/name`)
ShowHide 6 fields of
modelcatalog_model_idstring | nullrequiredID of the catalog model
repositorystringrequiredWhere the weights come from: a Hugging Face repository `<owner>/<name>`, or a `fine-tuned://` URI for a fine-tuned model
filestring | nullrequiredThe weights file or quantisation tag chosen in the repository; null when the whole repository is used
revisionstring | nullrequiredBranch, tag or commit; null for the repository's default branch
token_secret_idstring | nullrequiredID of the token secret
fine_tuned_model_idstring | nullrequiredSet when the deployment serves a fine-tuned model (then `repository` is its `fine-tuned://` URI)
`llama_cpp`: GGUF chat and completion models (CPU or GPU). `tei`: embedding and rerank models. `vllm`: chat, completion and embedding models on GPUs.
One of
llama_cppteivllmhardwareobjectrequiredThe hardware each replica runs on and its GPUs per replica
ShowHide 2 fields of
hardwareskustringrequiredHardware type code
gpu_countintegerrequiredNumber of GPUs
regionstringrequiredRegion code
engine_optionsobjectrequiredEngine settings chosen for this deployment
ShowHide 2 fields of
engine_optionscontext_lengthinteger | nullrequiredContext length in tokens per request; null: the engine's default
parallelinteger | nullrequiredRequests one replica runs at once; null: the engine's default
disk_gbintegerrequiredDisk per replica for the weights, in GB
min_replicasintegerrequiredFewest replicas kept running while the endpoint runs
max_replicasintegerrequiredMost replicas the autoscaler may run
autoscalingobjectrequiredHow the replica count follows demand
ShowHide 1 field of
autoscalingtarget_concurrencyintegerrequiredConcurrent requests per replica the autoscaler aims for: replicas = ceil(concurrency / target), between min and max
traffic_weightintegerrequiredPercentage of the endpoint's requests sent to this deployment (0–100; the weights of an endpoint's deployments sum to 100)
ShowHide 4 fields of
replicasreadyintegerrequiredReplicas taking traffic
startingintegerrequiredReplicas downloading weights or loading the model
unhealthyintegerrequiredReplicas that were ready but are failing health checks (no traffic)
drainingintegerrequiredReplicas finishing their requests before removal
last_failurestring | nullrequiredWhy 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)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
Example response
{
"object": "dedicated_endpoint",
"id": "ded_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"name": "string",
"display_name": "string",
"model": "acme/support-bot",
"type": "chat",
"context_length": 1,
"status": "stopped",
"desired_state": "running",
"stop_reason": "string",
"inactivity_timeout_seconds": 1,
"last_request_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"stopped_at": "2026-01-01T00:00:00.000Z",
"deployments": [
{
"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"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_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. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
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. |