API reference
API reference
Hayonix API 1.0.0: 205 operations, generated from the OpenAPI document the SDKs and the CLI are built from.
The control-plane API is served at API_BASE_URL, which ends in /v1. Version 1 only grows: fields and operations are added, never removed or renamed. JSON is snake_case, amounts are integer nano-USD in decimal strings, and times are ISO 8601 in UTC.
- Authenticate with a project API key:
Authorization: Bearer sk_…. See Projects and API keys. - Errors share one envelope; lists are cursor-paginated; creating requests accept an Idempotency-Key.
- The OpenAI-compatible routes (chat, completions, embeddings, rerank, models) are described in Inference API.
- Operations marked Console session are called by the console and refuse API keys.
Account
Organizations
Members
Invitations
- GETList invitations
/v1/orgs/{org_id}/invitations - POSTInvite someone by email (a pending invitation to the same address is replaced)
/v1/orgs/{org_id}/invitations - DELETECancel a pending invitation
/v1/orgs/{org_id}/invitations/{invitation_id} - POSTAccept an invitation addressed to your verified email
/v1/orgs/{org_id}/invitations/{invitation_id}/accept
Projects
- GETList projects
/v1/orgs/{org_id}/projects - POSTCreate a project
/v1/orgs/{org_id}/projects - GETGet a project
/v1/orgs/{org_id}/projects/{project_id} - PATCHUpdate a project
/v1/orgs/{org_id}/projects/{project_id} - POSTArchive a project (projects are never deleted)
/v1/orgs/{org_id}/projects/{project_id}/archive - POSTRestore an archived project
/v1/orgs/{org_id}/projects/{project_id}/unarchive
API keys
SSH keys
Secrets
Registry credentials
- GETList registry credentials
/v1/registry-credentials - POSTAdd registry credentials
/v1/registry-credentials - GETGet registry credentials (without the password)
/v1/registry-credentials/{registry_credential_id} - PATCHUpdate registry credentials
/v1/registry-credentials/{registry_credential_id} - DELETEDelete registry credentials
/v1/registry-credentials/{registry_credential_id}
Audit logs
Billing
- GETGet the credit balance
/v1/orgs/{org_id}/billing/balance - GETBilling settings, credit standing, spend limits, auto-recharge and limits
/v1/orgs/{org_id}/billing/account - PATCHSet the low-balance alert threshold and spend limits (null clears)
/v1/orgs/{org_id}/billing/account - GETThe rate-limit level: per-minute limits in force and what reaches the next level
/v1/orgs/{org_id}/billing/rate-level - PATCHTurn auto-recharge on or off (threshold → target, monthly cap, saved card)
/v1/orgs/{org_id}/billing/auto-recharge - POSTStart a top-up: returns a payment with the checkout URL to send the customer to
/v1/orgs/{org_id}/billing/top-ups - GETPayment history (top-ups and auto-recharges) with receipt links
/v1/orgs/{org_id}/billing/payments - GETGet a payment (the console polls this after Checkout)
/v1/orgs/{org_id}/billing/payments/{payment_id} - GETSaved cards
/v1/orgs/{org_id}/billing/payment-methods - POSTRemove a saved card (turns off auto-recharge if it used this card)
/v1/orgs/{org_id}/billing/payment-methods/{payment_method_id}/detach - POSTRedeem a promo code for promotional credit
/v1/orgs/{org_id}/billing/promo-redemptions - GETBilling emails sent to the organization (low balance, out of credit, payments …)
/v1/orgs/{org_id}/billing/notices
Pricing
Pods
- GETHardware for pods: per SKU, its prices and what can be launched now in each region
/v1/pods/hardware - GETPrice estimate for a pod configuration: hourly running and stopped cost
/v1/pods/estimate - GETList pods in the project (terminated pods are left out unless asked for)
/v1/pods - POSTCreate a pod from a template or an image (launch gate and quotas apply)
/v1/pods - GETGet a pod: its state, configuration and how to connect
/v1/pods/{pod_id} - PATCHRename a pod (does not touch the container)
/v1/pods/{pod_id} - POSTChange a pod’s configuration (recreates the container; only volume data survives)
/v1/pods/{pod_id}/reconfigure - POSTStart a stopped pod (placed again; on its volume’s host if it has one)
/v1/pods/{pod_id}/start - POSTStop a pod: compute released and no longer billed; volumes kept (and billed)
/v1/pods/{pod_id}/stop - POSTRestart the container in place (same host and GPUs; the container disk is kept)
/v1/pods/{pod_id}/restart - POSTReset a pod: recreate its container from the image with a fresh container disk (volumes kept)
/v1/pods/{pod_id}/reset - POSTTerminate a pod: the container is destroyed; its pod volume is deleted unless kept
/v1/pods/{pod_id}/terminate - POSTRun a command in the pod and wait for it (bounded time and output)
/v1/pods/{pod_id}/exec - POSTA single-use ticket (valid for seconds) to open the pod’s terminal WebSocket
/v1/pods/{pod_id}/terminal-tickets - GETThe pod’s timeline (oldest first): what the platform did and what its host reported
/v1/pods/{pod_id}/events - GETContainer output and platform events as a server-sent event stream
/v1/pods/{pod_id}/logs - GETCPU, memory, disk, network and GPU series for a time range
/v1/pods/{pod_id}/telemetry - POSTSave a pod’s configuration as a template (secrets are dropped from public ones)
/v1/pods/{pod_id}/templates
Templates
- GETTemplates you can launch: official, public and your organization’s private ones
/v1/templates - POSTCreate a private (organization) or public template
/v1/templates - GETGet a template
/v1/templates/{template_id} - PATCHUpdate one of your organization’s templates (pods made from it are not changed)
/v1/templates/{template_id} - DELETEDelete one of your organization’s templates (pods made from it keep running)
/v1/templates/{template_id}
Volumes
- GETList live volumes in the project
/v1/volumes - POSTCreate a network volume (billed per GB-second until deleted)
/v1/volumes - GETGet a volume, where it is pinned and which pods mount it
/v1/volumes/{volume_id} - PATCHRename a volume
/v1/volumes/{volume_id} - DELETEDelete an unattached volume and its data (irreversible; billing stops now)
/v1/volumes/{volume_id} - POSTGrow a volume (sizes never shrink)
/v1/volumes/{volume_id}/grow - POSTMount the volume in a pod (recreates the pod’s container; see the plan)
/v1/volumes/{volume_id}/attach - POSTUnmount the volume from a pod (recreates the pod’s container; the data is kept)
/v1/volumes/{volume_id}/detach
Serverless
- GETList serverless endpoints in the project
/v1/serverless/endpoints - POSTCreate a serverless endpoint (the webhook secret is returned once)
/v1/serverless/endpoints - GETGet a serverless endpoint
/v1/serverless/endpoints/{endpoint_id} - PATCHUpdate an endpoint. Changing the image, command, environment, SKUs, GPU count, concurrency, disk or HTTP settings creates a new release; workers are replaced progressively (busy ones finish first; an HTTP endpoint keeps old workers serving until new ones are healthy).
/v1/serverless/endpoints/{endpoint_id} - DELETEDelete an endpoint: its jobs are canceled and its workers removed
/v1/serverless/endpoints/{endpoint_id} - POSTReplace the webhook signing secret (returned once)
/v1/serverless/endpoints/{endpoint_id}/rotate-webhook-secret - GETRelease history, newest first
/v1/serverless/endpoints/{endpoint_id}/releases - GETGet a release
/v1/serverless/releases/{release_id} - POSTRoll back: a new release with an earlier release's worker spec
/v1/serverless/endpoints/{endpoint_id}/rollback - GETList jobs of an endpoint, newest first
/v1/serverless/endpoints/{endpoint_id}/jobs - POSTSubmit a job. With `wait`, answer once it finishes or the wait runs out (then poll the job).
/v1/serverless/endpoints/{endpoint_id}/jobs - GETJob status and result. With `wait`, long-poll until it finishes.
/v1/serverless/jobs/{job_id} - GETPartial output streamed by the handler, in order (long-poll with `wait`)
/v1/serverless/jobs/{job_id}/stream - POSTCancel a queued or running job (a running handler is told to stop)
/v1/serverless/jobs/{job_id}/cancel - POSTCancel every queued job of the endpoint (running jobs continue)
/v1/serverless/endpoints/{endpoint_id}/purge-queue - GETQueue depth, jobs by state, workers by state and rollout progress
/v1/serverless/endpoints/{endpoint_id}/health - GETQueue delay, execution time, cold starts and job counts over time
/v1/serverless/endpoints/{endpoint_id}/metrics - GETHTTP endpoints: request rate, status classes, latency percentiles, requests in flight and cold-start waits over time, per endpoint and per worker
/v1/serverless/endpoints/{endpoint_id}/request-metrics - GETWorkers of the endpoint with their state (live ones and those removed in the last hour)
/v1/serverless/endpoints/{endpoint_id}/workers - GETRecent container logs of the endpoint's workers
/v1/serverless/endpoints/{endpoint_id}/logs - GETCompletion webhook deliveries with their attempt log, newest first
/v1/serverless/endpoints/{endpoint_id}/webhook-deliveries
Models
- GETList catalog models (public ones; with credentials, also the project's private ones)
/v1/catalog/models - GETGet a catalog model (private models only for their own project)
/v1/catalog/models/{model_id} - POSTMint a short-lived playground token for the inference API (signed-in users only)
/v1/playground-tokens
Model references
- GETList the project’s model references
/v1/model-references - POSTAccept a model reference (checked against the model hub, pinned to a commit)
/v1/model-references - GETGet a model reference and the files it resolved to
/v1/model-references/{reference_id} - DELETEDelete a model reference nothing mounts
/v1/model-references/{reference_id}
Dedicated endpoints
- GETList dedicated endpoints in the project, newest first
/v1/endpoints - POSTCreate a dedicated endpoint (a catalog model or your own Hugging Face model) with its first deployment
/v1/endpoints - GETGet a dedicated endpoint with its deployments and replica counts
/v1/endpoints/{dedicated_endpoint_id} - PATCHUpdate the display name or the inactivity timeout
/v1/endpoints/{dedicated_endpoint_id} - DELETEDelete an endpoint: its replicas are removed and its model ID stops resolving
/v1/endpoints/{dedicated_endpoint_id} - POSTStart a stopped endpoint (needs credit; replicas start and are billed once ready)
/v1/endpoints/{dedicated_endpoint_id}/start - POSTStop an endpoint: its replicas are removed and billing for them ends
/v1/endpoints/{dedicated_endpoint_id}/stop - GETAn endpoint's deployments
/v1/endpoints/{dedicated_endpoint_id}/deployments - POSTAdd a deployment (other weights, engine or hardware). It starts with no traffic; give it a share with the traffic split.
/v1/endpoints/{dedicated_endpoint_id}/deployments - GETGet a deployment
/v1/endpoint-deployments/{deployment_id} - PATCHChange replica bounds or the autoscaling target (replicas are not recreated)
/v1/endpoint-deployments/{deployment_id} - DELETEDelete a deployment that carries no traffic; its replicas are removed
/v1/endpoint-deployments/{deployment_id} - PUTSet the share of requests each deployment receives (weights sum to 100)
/v1/endpoints/{dedicated_endpoint_id}/traffic - GETAn endpoint's replicas, newest first
/v1/endpoints/{dedicated_endpoint_id}/replicas - GETWhat happened to an endpoint, newest first
/v1/endpoints/{dedicated_endpoint_id}/events - GETRequests, errors, tokens, latency and billed replica time, by deployment and over time
/v1/endpoints/{dedicated_endpoint_id}/analytics - GETPublic catalog models a dedicated endpoint can serve, with the engine used on CPU and on GPU hardware
/v1/endpoint-models
Files
- GETList files in the project
/v1/files - POSTUpload a file (multipart form: file, purpose); validated asynchronously
/v1/files - GETThe upload size cap, the purposes and the validation limits
/v1/files/limits - GETGet a file, with its validation state and report
/v1/files/{file_id} - DELETEDelete a file
/v1/files/{file_id} - GETDownload a file's content
/v1/files/{file_id}/content - POSTA short-lived link to download a file's content without credentials
/v1/files/{file_id}/download-link - GETDownload through a signed link (no credentials: the token is the credential)
/v1/downloads
Fine-tuning
- GETModels that can be fine-tuned, how, on which hardware and at what price
/v1/fine-tunes/base-models - GETPrice estimate for fine-tuning on a validated dataset
/v1/fine-tunes/estimate - GETList fine-tuning jobs, newest first
/v1/fine-tunes - POSTCreate a fine-tuning job (reserves its estimated cost; 402 when credit is short)
/v1/fine-tunes - GETGet a fine-tuning job
/v1/fine-tunes/{fine_tune_id} - POSTCancel a job (charged only for the tokens it trained; idempotent)
/v1/fine-tunes/{fine_tune_id}/cancel - GETA job's events, oldest first
/v1/fine-tunes/{fine_tune_id}/events - GETA job's training metrics, one point per step in step order (chart-ready)
/v1/fine-tunes/{fine_tune_id}/metrics - GETA job's checkpoints, oldest first
/v1/fine-tunes/{fine_tune_id}/checkpoints - GETDownload the adapter or the merged weights of a checkpoint as a tar archive
/v1/fine-tunes/{fine_tune_id}/download - POSTA short-lived link to download an artefact tar without credentials
/v1/fine-tunes/{fine_tune_id}/download-link - GETThe project's fine-tuned models (results of succeeded jobs), newest first
/v1/fine-tuned-models - GETGet a fine-tuned model of the project
/v1/fine-tuned-models/{fine_tuned_model_id} - DELETEDelete a fine-tuned model (refused with 409 while it is served)
/v1/fine-tuned-models/{fine_tuned_model_id} - POSTServe a LoRA fine-tune per token on the shared pool of its base model (idempotent)
/v1/fine-tuned-models/{fine_tuned_model_id}/enable - POSTStop serving a fine-tune per token (idempotent)
/v1/fine-tuned-models/{fine_tuned_model_id}/disable
Batches
- GETList batches in the project, newest first
/v1/batches - POSTCreate a batch from an uploaded file of requests (validated and run asynchronously)
/v1/batches - GETGet a batch: status, request counts, stage times, cost so far
/v1/batches/{batch_id} - GETList the lines of a batch in input order: status, error, tokens and cost
/v1/batches/{batch_id}/lines - POSTCancel a batch (requests in flight may finish; completed ones are kept and charged)
/v1/batches/{batch_id}/cancel
Evaluations
- GETList the models this project can use as a judge or to generate candidates
/v1/evaluations/models - POSTEstimate an evaluation: the most it can cost, and its first row’s requests
/v1/evaluations/estimate - GETList evaluations in the project, newest first
/v1/evaluations - POSTCreate an evaluation over an uploaded dataset (validated and run asynchronously)
/v1/evaluations - GETGet an evaluation: status, progress, results so far, cost
/v1/evaluations/{evaluation_id} - POSTCancel an evaluation (calls in flight may finish; finished rows are kept)
/v1/evaluations/{evaluation_id}/cancel - GETList an evaluation’s rows in dataset order: verdict, reasoning, texts, cost
/v1/evaluations/{evaluation_id}/rows
Sandboxes
- GETSandbox sizes with their prices, and the limits that apply to sandboxes and runs
/v1/sandboxes/sizes - GETList sandboxes in the project, newest first (ended ones only when asked for)
/v1/sandboxes - POSTCreate a sandbox (launch gate and quotas apply); it ends by itself at its deadline
/v1/sandboxes - GETGet a sandbox: its state, time left and cost so far
/v1/sandboxes/{sandbox_id} - POSTMove its deadline later (never past its maximum lifetime)
/v1/sandboxes/{sandbox_id}/extend - POSTEnd a sandbox now: runs are cut off, its files are deleted, billing stops
/v1/sandboxes/{sandbox_id}/end - GETRuns of a sandbox, newest first (kept until 7 days after it ends)
/v1/sandboxes/{sandbox_id}/runs - POSTRun code in the sandbox and wait for the result (or stream it)
/v1/sandboxes/{sandbox_id}/runs - GETOne run: its outcome and recorded output
/v1/sandboxes/{sandbox_id}/runs/{run_id} - GETA run’s output as a server-sent event stream, from its start until it ends
/v1/sandboxes/{sandbox_id}/runs/{run_id}/events - POSTStop a queued or running run (a finished run is returned as it is)
/v1/sandboxes/{sandbox_id}/runs/{run_id}/cancel - GETList a directory of the sandbox’s workspace
/v1/sandboxes/{sandbox_id}/files - DELETEDelete a file, or a directory with everything in it, from the workspace
/v1/sandboxes/{sandbox_id}/files - GETDownload a file from the sandbox’s workspace (streamed)
/v1/sandboxes/{sandbox_id}/files/content - PUTUpload a file into the sandbox’s workspace (replaces it; parents are created)
/v1/sandboxes/{sandbox_id}/files/content
Clusters
- GETWhat a cluster of this shape costs per hour at today’s prices
/v1/clusters/estimate - GETList clusters in the project, newest first (deleted ones only when asked for)
/v1/clusters - POSTCreate a cluster: every member is placed on a host at once, or nothing is created
/v1/clusters - GETGet a cluster: its state, its members (rank, host, address, state) and how to connect
/v1/clusters/{cluster_id} - PATCHRename a cluster (nothing else about a cluster changes after creation)
/v1/clusters/{cluster_id} - DELETEDelete a cluster: every member, its network and its shared volume are destroyed
/v1/clusters/{cluster_id} - GETThe cluster’s timeline, oldest first
/v1/clusters/{cluster_id}/events - GETA member’s container output as a server-sent event stream
/v1/clusters/{cluster_id}/members/{rank}/logs
Usage
Webhooks
- GETEvery event type a webhook can receive, with the JSON Schema of its data
/v1/webhooks/event-types - GETList the project’s webhook destinations, with their delivery health
/v1/webhooks - POSTCreate a webhook destination (its signing secret is returned once)
/v1/webhooks - GETGet a webhook destination
/v1/webhooks/{webhook_id} - PATCHChange a webhook destination, or pause or resume it
/v1/webhooks/{webhook_id} - DELETEDelete a webhook destination and its delivery log
/v1/webhooks/{webhook_id} - POSTReplace the signing secret (returned once); the previous one keeps signing during the overlap
/v1/webhooks/{webhook_id}/rotate-secret - POSTSend a test event to this destination (also while it is paused)
/v1/webhooks/{webhook_id}/test - GETList a destination’s deliveries, newest first
/v1/webhooks/{webhook_id}/deliveries - GETGet a delivery with its payload and attempt log
/v1/webhooks/{webhook_id}/deliveries/{delivery_id} - POSTSend a delivery’s event again (a new delivery, same event ID)
/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver