# Hayonix documentation Generated from the same source as https://hayonix.ai/docs. Amounts are integer nano-USD in decimal strings; times are ISO 8601 in UTC. --- # Hayonix documentation URL: https://hayonix.ai/docs What you can run, how to reach it, and where to begin: inference, pods, serverless workers, fine-tuning and batches on one prepaid balance. Hayonix runs three kinds of work for you, all paid from one prepaid credit balance: - Inference: open models behind an OpenAI-compatible API. Existing OpenAI client code works once it points at our base URL. Shared models are billed per token; a dedicated endpoint gives a model its own replicas, billed per second while they are ready. - Compute: pods (a container on a GPU or CPU machine, with SSH, ports and persistent volumes) and serverless endpoints (your worker image, scaled from zero by a job queue). - Training: managed fine-tuning (LoRA or full) from a JSON Lines dataset, and batch inference over a file of requests at a lower price. ## How the pieces fit Everything you create belongs to a project inside an organization. An API key is issued for one project and can only see that project. The balance, members and billing settings belong to the organization. Two APIs serve your code: | API | Base URL variable | What it serves | | Control-plane REST API | API_BASE_URL | Pods, serverless, files, fine-tunes, batches, endpoints, billing and usage. Documented in the API reference. | | Inference API | INFERENCE_BASE_URL | The OpenAI-compatible routes: chat completions, completions, embeddings, rerank and models. See Inference API. | In production both are served from one host. The SDKs and the CLI read the same three environment variables, API_KEY, API_BASE_URL and INFERENCE_BASE_URL, so one setup serves every tool. ## Where to start 1. Set up a key and your environment. 2. Make your first inference call, or start a pod. 3. Read how billing and compute billing work before you leave anything running. Every code sample in the quickstarts and the SDK guides is a file that is executed against a real stack, so what you copy runs as shown. Machine-readable docs: /llms.txt lists every page with a one-line summary, and /llms-full.txt is the whole documentation, reference included, as plain text for coding assistants. --- # Set up a key and your environment URL: https://hayonix.ai/docs/get-started/setup Create a project API key, set the three environment variables every tool reads, and install the SDK or CLI you want to use. ## Create an API key In the console, open your project and go to API keys, then create a key. Give it a name that says where it will be used and only the scopes that code needs, for example inference:invoke for an application that only calls models. The key (it starts with sk_) is shown once, when it is created: store it in your secret manager straight away. See Projects and API keys for scopes and expiry. A key always acts in the project it was created in. You never pass a project ID with a key. ## Set the environment - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 Every example in these docs reads these variables, and so do both SDKs and the CLI. Some examples also read inputs such as MODEL; each one lists its inputs and their defaults. ## Install a client You can call the API with any HTTP client. The official tools add typed methods, retries, pagination, waiting helpers and the OpenAI client for inference. TypeScript (a current Node.js LTS release, Bun or Deno): ```sh npm install hayonix ``` Python 3.11 or later (the openai extra adds client.openai()): ```sh pip install "hayonix[openai]" ``` The command-line tool, hayonix: ```sh npm install -g hayonix-cli ``` ## Check that it works The SDK fetches who the key is (its org, project and permissions) on first use. This is the TypeScript SDK guide's first sample: TypeScript: ```typescript import { Client } from 'hayonix'; // API_KEY, API_BASE_URL and INFERENCE_BASE_URL come from the environment by default. const client = new Client({ timeout: 30_000, // per attempt, in milliseconds (default 60 000) maxRetries: 3, // retries of a retryable failure (default 2) }); const me = await client.caller(); // the key's org, project and permissions console.log('project:', me.project_id); ``` If this prints your project ID, you are ready for a quickstart. --- # Your first inference call URL: https://hayonix.ai/docs/quickstarts/inference Send a chat completion to an open model with curl, the SDKs or the official OpenAI clients, then stream the answer token by token. The inference API follows the OpenAI API, so you can use the SDKs below or keep the OpenAI client you already have and change two settings: the base URL and the key. ## Before you start You need an API key with the inference:invoke scope and the environment from Setup: - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 The samples read the model from MODEL. GET /v1/models lists every model your key can use; pick one whose serving field is true, because the catalog also lists models that have no replica running right now (base models for fine-tuning, for example). ## Send a chat completion With the SDKs, client.openai() returns the official OpenAI client already pointed at the inference base URL with your key. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, messages: [{role: "user", content: "Name three uses for a GPU in one sentence."}], max_completion_tokens: 64 }' | curl -sS "$INFERENCE_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | jq -r '"reply: " + (.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; "")), "tokens: \(.usage.total_tokens)"' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const client = new Client(); // reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL const openai = await client.openai(); const completion = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Name three uses for a GPU in one sentence.' }], max_completion_tokens: 64, }); console.log('reply:', completion.choices[0]?.message.content?.trim() ?? ''); console.log('tokens:', completion.usage?.total_tokens); ``` Python: ```python import os from hayonix import Client model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") client = Client() # reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL openai = client.openai() completion = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Name three uses for a GPU in one sentence."}], max_completion_tokens=64, ) print("reply:", (completion.choices[0].message.content or "").strip()) print("tokens:", completion.usage.total_tokens if completion.usage else None) ``` CLI: ```bash hayonix models list # The reply goes to stdout, the token count to stderr (shown here with 2>&1). hayonix chat "$MODEL" "Name three uses for a GPU in one sentence." --max-tokens 64 --no-stream 2>&1 ``` The response is the OpenAI chat completion object. usage holds the token counts you are billed for, as the engine reported them. ## Use the OpenAI client directly If you do not want our SDK, construct the OpenAI client yourself with our base URL: TypeScript: ```typescript import OpenAI from 'openai'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const plain = new OpenAI({ apiKey: process.env.API_KEY, baseURL: process.env.INFERENCE_BASE_URL, }); const again = await plain.chat.completions.create({ model, messages: [{ role: 'user', content: 'Say hello in five words.' }], max_completion_tokens: 32, }); console.log('reply:', again.choices[0]?.message.content?.trim() ?? ''); ``` Python: ```python import os from openai import OpenAI model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") plain = OpenAI( api_key=os.environ["API_KEY"], base_url=os.environ["INFERENCE_BASE_URL"], ) again = plain.chat.completions.create( model=model, messages=[{"role": "user", "content": "Say hello in five words."}], max_completion_tokens=32, ) print("reply:", (again.choices[0].message.content or "").strip()) ``` ## Stream the answer Set stream: true to receive server-sent events as tokens are generated. The stream ends with data: [DONE]. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, messages: [{role: "user", content: "Count from one to five."}], max_completion_tokens: 64, stream: true }' | curl -sS -N "$INFERENCE_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | sed -un 's/^data: //p' | grep --line-buffered -v '^\[DONE\]$' | jq -j '.choices[0].delta.content // empty' echo ``` TypeScript: ```typescript const stream = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Count from one to five.' }], max_completion_tokens: 64, stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta.content ?? ''); } process.stdout.write('\n'); ``` Python: ```python stream = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Count from one to five."}], max_completion_tokens=64, stream=True, ) for chunk in stream: if chunk.choices: print(chunk.choices[0].delta.content or "", end="", flush=True) print() ``` CLI: ```bash hayonix chat "$MODEL" "Count from one to five." --max-tokens 64 # streams by default ``` What a request costs: Each request reserves credit for its worst case (the prompt plus the most tokens it may generate) before it runs and settles at the real token count when it ends, so an out-of-credit key gets 402 up front instead of a surprise bill. A stream you cut off is billed for the prompt and the tokens already sent. See Billing and credit. ## Next - Inference API reference: every route, parameter and error. - Dedicated endpoints: a model on replicas of its own. --- # Your first pod URL: https://hayonix.ai/docs/quickstarts/pods Deploy a CPU pod from a public image, wait until it runs, run a command inside it, and terminate it so billing stops. A pod is one container on one machine, with the hardware you choose. It keeps running until you stop or terminate it, and it is billed per second while it runs. ## Before you start - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 The samples take three inputs: IMAGE (default busybox:1.37.0), SKU (default cpu-2c-4gb, a small CPU machine) and REGION. GET /v1/pods/hardware lists every SKU, its price and where it can be launched now. ## Deploy the pod The pod runs sleep infinity so the container keeps running: when a pod's command exits, the pod is exited. volume: null asks for no persistent volume. curl: ```bash POD_ID=$( jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "quickstart", image: $image, command: ["sleep", "infinity"], hardware: {sku: $sku, gpu_count: 0}, region: $region, volume: null }' | curl -sS --fail-with-body "$API_BASE_URL/pods" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | jq -r .id ) echo "created $POD_ID" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const image = process.env.IMAGE ?? 'busybox:1.37.0'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const pod = await client.pods.create({ name: 'quickstart', image, command: ['sleep', 'infinity'], hardware: { sku, gpu_count: 0 }, region, volume: null, }); console.log('created', pod.id); ``` Python: ```python import os from hayonix import Client client = Client() image = os.environ.get("IMAGE", "busybox:1.37.0") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") pod = client.pods.create( name="quickstart", image=image, command=["sleep", "infinity"], hardware={"sku": sku, "gpu_count": 0}, region=region, volume=None, ) print("created", pod["id"]) ``` CLI: ```bash hayonix pods hardware # SKUs, prices and where each can launch now # `pods deploy` has no flag for the container's command, so this goes through `api`, which takes # any request body. For an image whose own command keeps running, `pods deploy` is enough: # platform pods deploy --name web --image IMAGE --sku SKU --region REGION --wait BODY=$(jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "quickstart", image: $image, command: ["sleep", "infinity"], hardware: {sku: $sku, gpu_count: 0}, region: $region, volume: null }') POD_ID=$(hayonix api pods.create --body "$BODY" -q) echo "created $POD_ID" ``` The call returns at once with the pod in its first state; placing it, pulling the image and starting the container happen in the background. ## Wait until it runs The SDK waiters poll the pod until it reaches running, and stop with an error if it reaches a state it cannot leave by itself (failed, exited). curl: ```bash for _ in $(seq 1 300); do STATE=$(curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID" \ -H "Authorization: Bearer $API_KEY" | jq -r .status.state) [ "$STATE" = running ] && break case "$STATE" in failed|exited|terminated) echo "pod $STATE"; exit 1 ;; esac sleep 2 done echo "state: $STATE" ``` TypeScript: ```typescript const running = await client.waitFor.pod(pod.id); // until its state is `running` console.log('state:', running.status.state); ``` Python: ```python running = client.wait_for.pod(pod["id"]) # until its state is `running` print("state:", running["status"]["state"]) ``` CLI: ```bash until [ "$(hayonix pods show "$POD_ID" --json | jq -r .status.state)" = running ]; do sleep 2; done hayonix pods show "$POD_ID" ``` ## Run a command in it exec runs a command in the container and waits for it, with a time limit of up to 120 seconds and at most 1 MiB of output per stream. For an interactive shell use SSH or the console's terminal. curl: ```bash curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID/exec" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"command": ["uname", "-a"], "timeout_seconds": 10}' | jq -r '"exit code: \(.exit_code)", (.stdout | rtrimstr("\n"))' ``` TypeScript: ```typescript const result = await client.pods.exec(pod.id, { command: ['uname', '-a'], timeout_seconds: 10 }); console.log('exit code:', result.exit_code); console.log(result.stdout.trim()); ``` Python: ```python result = client.pods.exec(pod["id"], command=["uname", "-a"], timeout_seconds=10) print("exit code:", result["exit_code"]) print(result["stdout"].strip()) ``` CLI: ```bash hayonix pods exec "$POD_ID" -- uname -a ``` ## Reset it A reset recreates the container from its image on the same host: everything written to the container disk is gone, while volumes, the pod's addresses and its settings are kept. A restart (/restart) keeps the container disk instead. curl: ```bash # A reset recreates the container from its image: the container disk is fresh, volumes stay. run() { jq -n --arg cmd "$1" '{command: ["sh", "-c", $cmd], timeout_seconds: 10}' | curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID/exec" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- | jq -r '.stdout | rtrimstr("\n")' } run 'echo scratch > /tmp/scratch.txt' curl -sS --fail-with-body -X POST "$API_BASE_URL/pods/$POD_ID/reset" \ -H "Authorization: Bearer $API_KEY" >/dev/null until [ "$(curl -sS --fail-with-body "$API_BASE_URL/pods/$POD_ID" \ -H "Authorization: Bearer $API_KEY" | jq -r .status.state)" = running ]; do sleep 2; done echo "after reset: $(run 'cat /tmp/scratch.txt 2>/dev/null || echo "container disk is fresh"')" ``` TypeScript: ```typescript // A reset recreates the container from its image: the container disk is fresh, volumes stay. await client.pods.exec(pod.id, { command: ['sh', '-c', 'echo scratch > /tmp/scratch.txt'] }); await client.pods.reset(pod.id); await client.waitFor.pod(pod.id); const check = await client.pods.exec(pod.id, { command: ['sh', '-c', 'cat /tmp/scratch.txt 2>/dev/null || echo "container disk is fresh"'], }); console.log('after reset:', check.stdout.trim()); ``` Python: ```python # A reset recreates the container from its image: the container disk is fresh, volumes stay. client.pods.exec(pod["id"], command=["sh", "-c", "echo scratch > /tmp/scratch.txt"]) client.pods.reset(pod["id"]) client.wait_for.pod(pod["id"]) check = client.pods.exec( pod["id"], command=["sh", "-c", 'cat /tmp/scratch.txt 2>/dev/null || echo "container disk is fresh"'], ) print("after reset:", check["stdout"].strip()) ``` CLI: ```bash # A reset recreates the container from its image: the container disk is fresh, volumes stay. hayonix pods exec "$POD_ID" -- sh -c 'echo scratch > /tmp/scratch.txt' hayonix pods reset "$POD_ID" -y --wait echo "after reset: $(hayonix pods exec "$POD_ID" -- sh -c 'cat /tmp/scratch.txt 2>/dev/null || echo "container disk is fresh"')" ``` ## Terminate it Terminating destroys the container and, unless you ask to keep it, the pod's volume. Billing stops at once. Stopping instead keeps volumes (which are still billed) so you can start the pod again later. curl: ```bash terminate() { curl -sS --fail-with-body -X POST "$API_BASE_URL/pods/$POD_ID/terminate" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{}' >/dev/null echo "terminated $POD_ID" } trap terminate EXIT ``` TypeScript: ```typescript await client.pods.terminate(pod.id); console.log('terminated', pod.id); ``` Python: ```python client.pods.terminate(pod["id"]) print("terminated", pod["id"]) ``` CLI: ```bash trap 'platform pods terminate "$POD_ID" -y' EXIT ``` ## Next - How compute is billed: running, stopped and terminated. - Storage and volumes: what survives a stop, a reconfiguration and a terminate. --- # Your first serverless endpoint URL: https://hayonix.ai/docs/quickstarts/serverless Write a Python handler with the worker runtime, build it into an image, create an endpoint that scales from zero, run a job and read its streamed output. A serverless endpoint runs your worker image on demand. Jobs wait in the endpoint's queue; workers start when there is work and stop after they have been idle, so an endpoint with no jobs costs nothing. ## Write the handler A handler takes one job and returns a JSON value. A generator handler streams every value it yields to the caller while it runs, and its return value becomes the job's output. handler.py: ```python import time import serverless_worker as sw def handler(job: sw.Job): """Streams each word of the input text back, then returns a summary.""" words = str(job.input.get("text", "")).split() for i, word in enumerate(words): job.check_cancelled() # stop early when the job is canceled yield {"index": i, "word": word.upper()} time.sleep(0.1) return {"words": len(words)} if __name__ == "__main__": sw.serve(handler) ``` The worker runtime, serverless_worker (package hayonix-serverless-worker), has no third-party dependencies. Run the same file on your machine, without the platform, by passing a test input: Run the handler locally: ```bash python handler.py --test-input '{"text": "hello from a worker"}' ``` ## Build and push the image Start from the worker base image: Python with the runtime installed, running as an unprivileged user. Any Python image works too, after pip install hayonix-serverless-worker. Dockerfile: ```text # The worker base image: Python with the worker runtime, running as an unprivileged user. ARG BASE=registry.example.com/team/serverless-worker:0.1.0 FROM ${BASE} COPY handler.py /app/handler.py CMD ["python", "/app/handler.py"] ``` Build and push: ```bash IMAGE=registry.example.com/team/word-streamer:1.0.0 docker build -t "$IMAGE" . docker push "$IMAGE" ``` Push to a registry your endpoint can pull from. For a private registry, add a registry credential to the project and pass its ID as registry_credential_id. ## Create the endpoint The samples read the image reference from IMAGE. skus lists acceptable hardware in order of preference: each new worker takes the first SKU with capacity. curl: ```bash ENDPOINT_ID=$( jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "word-streamer", image: $image, skus: [$sku], region: $region, max_workers: 1 }' | curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r .id ) echo "endpoint $ENDPOINT_ID" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const image = process.env.IMAGE ?? 'registry.example.com/team/word-streamer:1.0.0'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const endpoint = await client.serverless.createEndpoint({ name: 'word-streamer', image, skus: [sku], region, max_workers: 1, }); console.log('endpoint', endpoint.id); ``` Python: ```python import json import os from hayonix import Client client = Client() image = os.environ.get("IMAGE", "registry.example.com/team/word-streamer:1.0.0") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") endpoint = client.serverless.create_endpoint( name="word-streamer", image=image, skus=[sku], region=region, max_workers=1, ) print("endpoint", endpoint["id"]) ``` CLI: ```bash ENDPOINT_ID=$(hayonix serverless create --name word-streamer --image "$IMAGE" \ --sku "$SKU" --region "$REGION" --max-workers 1 -q) echo "endpoint $ENDPOINT_ID" ``` The response also holds webhook_secret, which signs completion webhooks. It is returned only here; see Webhooks. ## Run a job and follow its output Submitting a job returns at once with the job queued. The first job on an idle endpoint waits for a worker to start and pull the image (a cold start). The stream long-polls, so chunks arrive as the handler yields them. curl: ```bash JOB_ID=$( curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID/jobs" \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"input": {"text": "hello from a worker"}}' | jq -r .id ) # Long-poll the stream: each page has the chunks after `next_after`, until `done`. AFTER=0 while :; do PAGE=$(curl -sS --fail-with-body \ "$API_BASE_URL/serverless/jobs/$JOB_ID/stream?after=$AFTER&wait=20" -H "$AUTH") echo "$PAGE" | jq -c '.chunks[] | "chunk: \(.data | tojson)"' -r AFTER=$(echo "$PAGE" | jq .next_after) [ "$(echo "$PAGE" | jq .done)" = true ] && break done curl -sS --fail-with-body "$API_BASE_URL/serverless/jobs/$JOB_ID?wait=60" -H "$AUTH" | jq -r '"state: \(.state) output: \(.output | tojson)"' ``` TypeScript: ```typescript const job = await client.serverless.submitJob(endpoint.id, { input: { text: 'hello from a worker' }, }); for await (const chunk of client.follow.jobStream(job.id)) { console.log('chunk:', JSON.stringify(chunk.data)); } const done = await client.waitFor.job(job.id); console.log('state:', done.state, 'output:', JSON.stringify(done.output)); ``` Python: ```python job = client.serverless.submit_job(endpoint["id"], input={"text": "hello from a worker"}) for chunk in client.follow.job_stream(job["id"]): print("chunk:", json.dumps(chunk.get("data"))) done = client.wait_for.job(job["id"]) print("state:", done["state"], "output:", json.dumps(done.get("output"))) ``` CLI: ```bash # Prints each streamed chunk as it arrives, then the output; exits 6 unless the job succeeds. hayonix serverless run "$ENDPOINT_ID" --input '{"text": "hello from a worker"}' --stream ``` To wait for a short job in the same call, submit it with wait (up to 60 seconds): the response is the finished job, or the job still running when the wait runs out. ## Delete the endpoint Deleting cancels the endpoint's open jobs and removes its workers. curl: ```bash delete_endpoint() { curl -sS --fail-with-body -X DELETE "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID" \ -H "$AUTH" >/dev/null echo "deleted $ENDPOINT_ID" } trap delete_endpoint EXIT ``` TypeScript: ```typescript await client.serverless.deleteEndpoint(endpoint.id); console.log('deleted', endpoint.id); ``` Python: ```python client.serverless.delete_endpoint(endpoint["id"]) print("deleted", endpoint["id"]) ``` CLI: ```bash trap 'platform serverless delete "$ENDPOINT_ID" -y' EXIT ``` ## Next - Webhooks: get a signed callback when a job finishes. - Idempotency: submit jobs safely from a retrying client. --- # Your first fine-tune URL: https://hayonix.ai/docs/quickstarts/fine-tuning Upload a small chat dataset, train a LoRA adapter on a base model, follow the job as it runs, and download the trained adapter. A fine-tuning job trains a base model on your examples and stores the result as a new private model in your project. You pay per training token; the estimated cost is reserved when the job is created. ## Upload a dataset Training data is a JSON Lines file with one example per line. For chat models each line is a conversation with at least one assistant message. Every uploaded file is validated in the background; wait for status: processed (valid) before you use it. An invalid file reports its errors with line numbers in validation.report. curl: ```bash # One JSON object per line: a conversation the model should learn to continue. for i in $(seq 0 15); do jq -cn --arg q "What is $i plus $i?" --arg a "$i plus $i is $((i + i))." \ '{messages: [{role: "user", content: $q}, {role: "assistant", content: $a}]}' done > "$WORK/train.jsonl" FILE_ID=$(curl -sS --fail-with-body "$API_BASE_URL/files" -H "$AUTH" \ -F purpose=fine-tune -F "file=@$WORK/train.jsonl" | jq -r .id) while STATUS=$(curl -sS "$API_BASE_URL/files/$FILE_ID" -H "$AUTH" | jq -r .status) [ "$STATUS" = uploaded ]; do sleep 1; done # validation runs in the background [ "$STATUS" = processed ] || { echo "file is not valid: $STATUS"; exit 1; } echo "uploaded $FILE_ID" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const baseModel = process.env.BASE_MODEL ?? 'HuggingFaceTB/SmolLM2-135M-Instruct'; // One JSON object per line: a conversation the model should learn to continue. const example = (q: string, a: string) => JSON.stringify({ messages: [ { role: 'user', content: q }, { role: 'assistant', content: a }, ], }); const lines = Array.from({ length: 16 }, (_, i) => example(`What is ${i} plus ${i}?`, `${i} plus ${i} is ${i + i}.`), ); const file = await client.files.upload({ file: { name: 'train.jsonl', data: lines.join('\n') + '\n' }, purpose: 'fine-tune', }); await client.waitFor.file(file.id); // until validation has passed console.log('uploaded', file.id); ``` Python: ```python import json import os from hayonix import Client client = Client() base_model = os.environ.get("BASE_MODEL", "HuggingFaceTB/SmolLM2-135M-Instruct") # One JSON object per line: a conversation the model should learn to continue. def example(q: str, a: str) -> str: return json.dumps({"messages": [{"role": "user", "content": q}, {"role": "assistant", "content": a}]}) lines = [example(f"What is {i} plus {i}?", f"{i} plus {i} is {i + i}.") for i in range(16)] file = client.files.upload( file=("train.jsonl", ("\n".join(lines) + "\n").encode()), purpose="fine-tune", ) client.wait_for.file(file["id"]) # until validation has passed print("uploaded", file["id"]) ``` CLI: ```bash for i in $(seq 0 15); do jq -cn --arg q "What is $i plus $i?" --arg a "$i plus $i is $((i + i))." \ '{messages: [{role: "user", content: $q}, {role: "assistant", content: $a}]}' done > train.jsonl FILE_ID=$(hayonix files upload train.jsonl --purpose fine-tune --wait -q) # waits for validation echo "uploaded $FILE_ID" ``` ## Create the job GET /v1/fine-tunes/base-models lists the models you can fine-tune (the samples read BASE_MODEL). The defaults train a LoRA adapter; set adapter.type to full for a full fine-tune. GET /v1/fine-tunes/estimate prices a run before you start it. curl: ```bash JOB_ID=$( jq -n --arg model "$BASE_MODEL" --arg file "$FILE_ID" '{ model: $model, training_file_id: $file, adapter: {type: "lora", rank: 8}, hyperparameters: {epochs: 1, batch_size: 4, max_seq_length: 128} }' | curl -sS --fail-with-body "$API_BASE_URL/fine-tunes" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r .id ) echo "fine-tune $JOB_ID" ``` TypeScript: ```typescript const job = await client.fineTuning.create({ model: baseModel, training_file_id: file.id, adapter: { type: 'lora', rank: 8 }, hyperparameters: { epochs: 1, batch_size: 4, max_seq_length: 128 }, }); console.log('fine-tune', job.id, job.state); ``` Python: ```python job = client.fine_tuning.create( model=base_model, training_file_id=file["id"], adapter={"type": "lora", "rank": 8}, hyperparameters={"epochs": 1, "batch_size": 4, "max_seq_length": 128}, ) print("fine-tune", job["id"], job["state"]) ``` CLI: ```bash JOB_ID=$(hayonix fine-tunes create --base-model "$BASE_MODEL" --training-file "$FILE_ID" \ --epochs 1 --batch-size 4 --lora-rank 8 -q) echo "fine-tune $JOB_ID" ``` A job is queued until compute is free, then launching, training, and finally succeeded, failed, cancelled or stopped (stopped by billing enforcement when the organization ran out of credit). ## Follow it Events describe what the job is doing (data prepared, training started, each checkpoint); metrics carry the loss curve. curl: ```bash while :; do STATE=$(curl -sS --fail-with-body "$API_BASE_URL/fine-tunes/$JOB_ID" -H "$AUTH" | jq -r .state) case "$STATE" in succeeded|failed|cancelled|stopped) break ;; esac sleep 5 done curl -sS --fail-with-body "$API_BASE_URL/fine-tunes/$JOB_ID/events?limit=200" -H "$AUTH" | jq -r '.data[] | "[\(.type)] \(.message)"' echo "state: $STATE" ``` TypeScript: ```typescript for await (const event of client.follow.fineTuneEvents(job.id)) { console.log(`[${event.type}] ${event.message}`); } const done = await client.fineTuning.get(job.id); console.log('state:', done.state); ``` Python: ```python for event in client.follow.fine_tune_events(job["id"]): print(f"[{event['type']}] {event['message']}") done = client.fine_tuning.get(job["id"]) print("state:", done["state"]) ``` CLI: ```bash hayonix fine-tunes follow "$JOB_ID" # prints events until the job finishes ``` ## Download the adapter A finished job has an adapter (LoRA) and, unless you turned merge_weights off, merged full weights. Both download as tar archives. curl: ```bash curl -sS --fail-with-body -o adapter.tar \ "$API_BASE_URL/fine-tunes/$JOB_ID/download?artifact=adapter" -H "$AUTH" echo "saved adapter.tar ($(wc -c < adapter.tar) bytes)" ``` TypeScript: ```typescript const archive = await client.fineTuning.download(job.id, { artifact: 'adapter' }); const bytes = await archive.saveTo('adapter.tar'); console.log(`saved adapter.tar (${bytes} bytes)`); ``` Python: ```python archive = client.fine_tuning.download(job["id"], artifact="adapter") size = archive.save("adapter.tar") print(f"saved adapter.tar ({size} bytes)") ``` CLI: ```bash hayonix fine-tunes download "$JOB_ID" --artifact adapter -o adapter.tar echo "saved adapter.tar ($(wc -c < adapter.tar) bytes)" ``` ## Export to Weights & Biases or Hugging Face A job can also log its training to Weights & Biases and upload the result to a Hugging Face model repository. Store the API key or access token as a project secret first, then name it in integrations: {"wandb": {"api_key_secret_id": "sec_…", "project": "…"}} and {"hugging_face": {"token_secret_id": "sec_…", "repository": "my-org/my-model", "artifact": "adapter"}} (or merged). The value never appears in the job; the trainer receives it when it starts. Both exports are best effort: if one fails (a refused key, a repository you cannot write to), the job still succeeds and an event says why. The console's fine-tuning form offers both under Exports. ## Next - Files: dataset formats and limits. - Fine-tuning reference: hyperparameters, checkpoints and the resulting models. --- # Your first batch URL: https://hayonix.ai/docs/quickstarts/batches Upload a file of inference requests, run them as a batch at batch prices, wait for it to finish and download the results. A batch runs many inference requests from one file, in the background, at the model's batch price. Use it for work that does not need an answer within seconds. ## Write and upload the requests Each line names a custom_id (your reference, unique in the file), the method POST, the route in url and the request body you would send to that route. Upload the file with purpose batch. curl: ```bash # One request per line; `custom_id` ties each result to its request. QUESTIONS=("What is a GPU?" "What is a CPU?") for i in "${!QUESTIONS[@]}"; do jq -cn --arg model "$MODEL" --arg id "question-$i" --arg q "${QUESTIONS[$i]}" '{ custom_id: $id, method: "POST", url: "/v1/chat/completions", body: {model: $model, messages: [{role: "user", content: $q}], max_completion_tokens: 32} }' done > "$WORK/requests.jsonl" INPUT_ID=$(curl -sS --fail-with-body "$API_BASE_URL/files" -H "$AUTH" \ -F purpose=batch -F "file=@$WORK/requests.jsonl" | jq -r .id) ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; // One request per line; `custom_id` ties each result to its request. const questions = ['What is a GPU?', 'What is a CPU?']; const lines = questions.map((q, i) => JSON.stringify({ custom_id: `question-${i}`, method: 'POST', url: '/v1/chat/completions', body: { model, messages: [{ role: 'user', content: q }], max_completion_tokens: 32 }, }), ); const input = await client.files.upload({ file: { name: 'requests.jsonl', data: lines.join('\n') + '\n' }, purpose: 'batch', }); ``` Python: ```python import json import os from hayonix import Client client = Client() model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") # One request per line; `custom_id` ties each result to its request. questions = ["What is a GPU?", "What is a CPU?"] lines = [ json.dumps( { "custom_id": f"question-{i}", "method": "POST", "url": "/v1/chat/completions", "body": {"model": model, "messages": [{"role": "user", "content": q}], "max_completion_tokens": 32}, } ) for i, q in enumerate(questions) ] input_file = client.files.upload( file=("requests.jsonl", ("\n".join(lines) + "\n").encode()), purpose="batch", ) ``` CLI: ```bash QUESTIONS=("What is a GPU?" "What is a CPU?") for i in "${!QUESTIONS[@]}"; do jq -cn --arg model "$MODEL" --arg id "question-$i" --arg q "${QUESTIONS[$i]}" '{ custom_id: $id, method: "POST", url: "/v1/chat/completions", body: {model: $model, messages: [{role: "user", content: $q}], max_completion_tokens: 32} }' done > requests.jsonl INPUT_ID=$(hayonix files upload requests.jsonl --purpose batch -q) ``` ## Create the batch endpoint is the route every line goes to: /v1/chat/completions, /v1/completions or /v1/embeddings. completion_window is 24h. curl: ```bash BATCH_ID=$( jq -n --arg file "$INPUT_ID" \ '{input_file_id: $file, endpoint: "/v1/chat/completions", completion_window: "24h"}' | curl -sS --fail-with-body "$API_BASE_URL/batches" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r .id ) echo "batch $BATCH_ID" ``` TypeScript: ```typescript const batch = await client.batches.create({ input_file_id: input.id, endpoint: '/v1/chat/completions', completion_window: '24h', }); console.log('batch', batch.id, batch.status); ``` Python: ```python batch = client.batches.create( input_file_id=input_file["id"], endpoint="/v1/chat/completions", completion_window="24h", ) print("batch", batch["id"], batch["status"]) ``` CLI: ```bash BATCH_ID=$(hayonix batches create --input-file "$INPUT_ID" --endpoint /v1/chat/completions -q) echo "batch $BATCH_ID" ``` ## Wait for it A batch is validating, then in_progress and finalizing, and ends completed, expired, failed or cancelled. Credit is reserved per request as it runs, so a batch that runs out of credit stops with partial results. curl: ```bash while :; do BATCH=$(curl -sS --fail-with-body "$API_BASE_URL/batches/$BATCH_ID" -H "$AUTH") STATUS=$(echo "$BATCH" | jq -r .status) echo "status: $STATUS" case "$STATUS" in completed|failed|expired|cancelled) break ;; esac sleep 5 done ``` TypeScript: ```typescript const done = await client.waitFor.batch(batch.id, { onUpdate: (b) => { console.log('status:', b.status); }, }); ``` Python: ```python done = client.wait_for.batch(batch["id"], on_update=lambda b: print("status:", b["status"])) ``` CLI: ```bash until platform batches show "$BATCH_ID" --json | jq -e '.status | IN("completed", "failed", "expired", "cancelled")' >/dev/null; do sleep 5 done hayonix batches show "$BATCH_ID" ``` ## Download the results output_file_id is a JSON Lines file with one line per request that succeeded: its custom_id and the response. Requests that failed are in error_file_id. Match results to requests by custom_id. curl: ```bash [ "$STATUS" = completed ] || exit 1 OUTPUT_ID=$(echo "$BATCH" | jq -r .output_file_id) curl -sS --fail-with-body "$API_BASE_URL/files/$OUTPUT_ID/content" -H "$AUTH" | jq -r '"\(.custom_id): " + (.response.body.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; ""))' ``` TypeScript: ```typescript if (done.status !== 'completed' || !done.output_file_id) throw new Error(`batch ${done.status}`); const output = await client.files.getContent(done.output_file_id); for (const line of (await output.text()).trim().split('\n')) { const result = JSON.parse(line) as { custom_id: string; response: { body: { choices: { message: { content: string | null } }[] } }; }; const reply = result.response.body.choices[0]?.message.content?.trim() ?? ''; console.log(`${result.custom_id}: ${reply}`); } ``` Python: ```python if done["status"] != "completed" or not done["output_file_id"]: raise SystemExit(f"batch {done['status']}") output = client.files.get_content(done["output_file_id"]) for line in output.text().strip().splitlines(): result = json.loads(line) reply = (result["response"]["body"]["choices"][0]["message"]["content"] or "").strip() print(f"{result['custom_id']}: {reply}") ``` CLI: ```bash OUTPUT_ID=$(hayonix batches show "$BATCH_ID" --json | jq -r .output_file_id) hayonix files download "$OUTPUT_ID" -o - | jq -r '"\(.custom_id): " + (.response.body.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; ""))' ``` The samples delete the input and output files at the end. Output files you keep are removed after output_expires_after (30 days by default). --- # Your first dedicated endpoint URL: https://hayonix.ai/docs/quickstarts/dedicated-endpoints Serve a catalog model on replicas of your own, wait until it is serving, chat with it through the OpenAI-compatible API, and delete it. A dedicated endpoint runs a model on replicas reserved for your project. Requests to it are not charged per token: you pay for each replica per second while it is ready, and it can stop by itself after a period without requests. ## Create the endpoint GET /v1/endpoint-models lists the catalog models an endpoint can serve and the engine each uses on CPU and on GPU hardware. You can also serve your own model from Hugging Face by giving model as {"source": "huggingface", "repository": …}. curl: ```bash curl -sS --fail-with-body "$API_BASE_URL/endpoint-models" -H "$AUTH" | jq -r '"deployable: " + ([.data[].model] | join(", "))' ENDPOINT=$( jq -n --arg model "$MODEL" --arg sku "$SKU" --arg region "$REGION" '{ name: "quickstart-bot", model: $model, hardware: {sku: $sku}, region: $region, min_replicas: 1, max_replicas: 1, inactivity_timeout_seconds: 600 }' | curl -sS --fail-with-body "$API_BASE_URL/endpoints" \ -H "$AUTH" -H "Content-Type: application/json" -d @- ) ENDPOINT_ID=$(echo "$ENDPOINT" | jq -r .id) ENDPOINT_MODEL=$(echo "$ENDPOINT" | jq -r .model) # the endpoint's own model ID echo "endpoint $ENDPOINT_ID serves $ENDPOINT_MODEL" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const { data: deployable } = await client.dedicatedEndpoints.listDeployableModels(); console.log('deployable:', deployable.map((m) => m.model).join(', ')); const endpoint = await client.dedicatedEndpoints.create({ name: 'quickstart-bot', model, // one of the deployable models hardware: { sku }, region, min_replicas: 1, max_replicas: 1, inactivity_timeout_seconds: 600, }); console.log('endpoint', endpoint.id, 'serves', endpoint.model); ``` Python: ```python import os from hayonix import Client client = Client() model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") deployable = [m["model"] for m in client.dedicated_endpoints.list_deployable_models()["data"]] print("deployable:", ", ".join(deployable)) endpoint = client.dedicated_endpoints.create( name="quickstart-bot", model=model, # one of the deployable models hardware={"sku": sku}, region=region, min_replicas=1, max_replicas=1, inactivity_timeout_seconds=600, ) print("endpoint", endpoint["id"], "serves", endpoint["model"]) ``` CLI: ```bash hayonix endpoints models # catalog models an endpoint can serve ENDPOINT_ID=$(hayonix endpoints create --name quickstart-bot --model "$MODEL" --sku "$SKU" \ --region "$REGION" --min-replicas 1 --max-replicas 1 --inactivity-timeout 600 -q) echo "endpoint $ENDPOINT_ID" ``` The endpoint's model field is its own model ID (/). Send that ID in inference requests to reach your replicas. ## Wait until it serves Starting means placing a replica, downloading the weights and loading them, which can take minutes for a large model. curl: ```bash for _ in $(seq 1 600); do STATUS=$(curl -sS --fail-with-body "$API_BASE_URL/endpoints/$ENDPOINT_ID" -H "$AUTH" | jq -r .status) [ "$STATUS" = serving ] && break [ "$STATUS" = failed ] && { echo "endpoint failed"; exit 1; } sleep 3 done echo "status: $STATUS" ``` TypeScript: ```typescript const serving = await client.waitFor.dedicatedEndpoint(endpoint.id); console.log('status:', serving.status); ``` Python: ```python serving = client.wait_for.dedicated_endpoint(endpoint["id"]) print("status:", serving["status"]) ``` CLI: ```bash until [ "$(hayonix endpoints show "$ENDPOINT_ID" --json | jq -r .status)" = serving ]; do sleep 3 done hayonix endpoints show "$ENDPOINT_ID" ``` ## Chat through it Requests use the same inference API as shared models, with the endpoint's model ID. curl: ```bash jq -n --arg model "$ENDPOINT_MODEL" '{ model: $model, messages: [{role: "user", content: "Say hello in five words."}], max_completion_tokens: 32 }' | curl -sS --fail-with-body "$INFERENCE_BASE_URL/chat/completions" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r '"reply: " + (.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; ""))' ``` TypeScript: ```typescript const openai = await client.openai(); const reply = await openai.chat.completions.create({ model: endpoint.model, // the endpoint's own model ID messages: [{ role: 'user', content: 'Say hello in five words.' }], max_completion_tokens: 32, }); console.log('reply:', reply.choices[0]?.message.content?.trim() ?? ''); ``` Python: ```python reply = client.openai().chat.completions.create( model=endpoint["model"], # the endpoint's own model ID messages=[{"role": "user", "content": "Say hello in five words."}], max_completion_tokens=32, ) print("reply:", (reply.choices[0].message.content or "").strip()) ``` CLI: ```bash ENDPOINT_MODEL=$(hayonix endpoints show "$ENDPOINT_ID" --json | jq -r .model) hayonix chat "$ENDPOINT_MODEL" "Say hello in five words." --max-tokens 32 --no-stream ``` ## Delete it curl: ```bash delete_endpoint() { curl -sS --fail-with-body -X DELETE "$API_BASE_URL/endpoints/$ENDPOINT_ID" -H "$AUTH" >/dev/null echo "deleted $ENDPOINT_ID" } trap delete_endpoint EXIT ``` TypeScript: ```typescript await client.dedicatedEndpoints.delete(endpoint.id); console.log('deleted', endpoint.id); ``` Python: ```python client.dedicated_endpoints.delete(endpoint["id"]) print("deleted", endpoint["id"]) ``` CLI: ```bash trap 'platform endpoints delete "$ENDPOINT_ID" -y' EXIT ``` inactivity_timeout_seconds stops an endpoint that has had no requests for that long (0 never stops it); a stopped endpoint costs nothing and can be started again. --- # Your first code sandbox URL: https://hayonix.ai/docs/quickstarts/sandboxes Create an isolated, short-lived sandbox, run Python, JavaScript and shell code in it, stream a run’s output, move files in and out, and end it so billing stops. A code sandbox is a small, isolated machine for running code you did not write yourself, such as code an AI agent generates. You send it code, it runs the code and answers with the output. Every sandbox is its own container under gVisor, an extra kernel boundary between the code and the host, and it is short-lived by design: it ends by itself, and nothing in it survives its end. ## Lifetime and billing A sandbox is billed per second from the moment it starts, at its size's price, until it ends. GET /v1/sandboxes/sizes lists the sizes with their per-hour and per-second prices; the default is cpu-2c-4gb. Sandboxes never get GPUs. A sandbox ends in one of three ways: - At its deadline. lifetime_seconds (default 3600) sets how long it lives. POST /v1/sandboxes/{sandbox_id}/extend moves the deadline later, but never more than 24 hours after the sandbox was created; lifetime.max_expires_at says how far it can go. - When it is idle. With no run and no file operation for idle_timeout_seconds (default 900), it ends. A run in progress counts as activity, and lifetime.idle_expires_at shows when the idle timeout falls due. - When you end it. POST /v1/sandboxes/{sandbox_id}/end cuts off any run in progress, deletes the sandbox's files and stops billing. end_reason records which of these happened (requested, expired, idle, or billing when the organization runs out of credit). Nothing is kept after a sandbox ends except its run records, which stay readable for 7 days. Anything you want to keep, download first. What a sandbox costs: A sandbox costs its size's per-second price for every second from start to end, whether code is running or not. The usage field of a sandbox shows the seconds billed so far and their cost. Short lifetimes and idle timeouts keep a forgotten sandbox from costing more than a few minutes. See How compute is billed. ## Before you start - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 The samples read REGION. A project can hold up to 5 live sandboxes, and the organization's sandboxes quota applies as well (see Quotas and limits). ## Create a sandbox The call answers at once with the sandbox in starting. It is placed on a machine and started in the background. curl: ```bash SANDBOX_ID=$( jq -n --arg region "$REGION" '{ name: "quickstart", region: $region, size: "cpu-2c-4gb", lifetime_seconds: 1800 }' | curl -sS --fail-with-body "$API_BASE_URL/sandboxes" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r .id ) echo "created $SANDBOX_ID" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const region = process.env.REGION ?? 'dev-local-1'; const sandbox = await client.sandboxes.create({ name: 'quickstart', region, size: 'cpu-2c-4gb', // GET /v1/sandboxes/sizes lists the sizes and their prices lifetime_seconds: 1800, // it ends by itself after 30 minutes }); console.log('created', sandbox.id, sandbox.status.state); ``` Python: ```python import os import time from hayonix import Client client = Client() region = os.environ.get("REGION", "dev-local-1") sandbox = client.sandboxes.create( name="quickstart", region=region, size="cpu-2c-4gb", # GET /v1/sandboxes/sizes lists the sizes and their prices lifetime_seconds=1800, # it ends by itself after 30 minutes ) print("created", sandbox["id"], sandbox["status"]["state"]) ``` CLI: ```bash hayonix api sandboxes.listSizes # sizes, their prices and the limits on runs and files BODY=$(jq -n --arg region "$REGION" \ '{name: "quickstart", region: $region, size: "cpu-2c-4gb", lifetime_seconds: 1800}') SANDBOX_ID=$(hayonix api sandboxes.create --body "$BODY" -q) echo "created $SANDBOX_ID" ``` ## Wait until it is ready A sandbox moves from starting to ready (waiting for code) and is busy while code runs. You do not have to wait for ready: a run sent while the sandbox starts waits for it. The samples wait explicitly so that the first run answers within the client's usual timeout. curl: ```bash while STATE=$(curl -sS --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID" -H "$AUTH" | jq -r .status.state) [ "$STATE" = starting ]; do sleep 2; done [ "$STATE" = ready ] || { echo "sandbox is $STATE"; exit 1; } echo "state: $STATE" ``` TypeScript: ```typescript // A run sent now would wait for the sandbox to start; this waits for it explicitly. let state = sandbox.status.state; while (state === 'starting') { await new Promise((r) => setTimeout(r, 2000)); state = (await client.sandboxes.get(sandbox.id)).status.state; } if (state !== 'ready') throw new Error(`sandbox is ${state}`); console.log('state:', state); ``` Python: ```python # A run sent now would wait for the sandbox to start; this waits for it explicitly. state = sandbox["status"]["state"] while state == "starting": time.sleep(2) state = client.sandboxes.get(sandbox["id"])["status"]["state"] if state != "ready": raise RuntimeError(f"sandbox is {state}") print("state:", state) ``` CLI: ```bash while STATE=$(hayonix api sandboxes.get "$SANDBOX_ID" --json | jq -r .status.state) [ "$STATE" = starting ]; do sleep 2; done [ "$STATE" = ready ] || { echo "sandbox is $STATE"; exit 1; } echo "state: $STATE" ``` ## Run code POST /v1/sandboxes/{sandbox_id}/runs takes a language and the code, and by default answers when the run has finished, with its whole output. curl: ```bash run() { # run LANGUAGE CODE [QUERY]: prints the run record jq -n --arg language "$1" --arg code "$2" '{language: $language, code: $code}' | curl -sS --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID/runs${3:-}" \ -H "$AUTH" -H "Content-Type: application/json" -d @- } run python 'x = 21 * 2' >/dev/null # One Python interpreter per sandbox: `x` is still defined in the next run. OUT=$(run python 'print(x)') echo "$OUT" | jq -r '"outcome: \(.outcome) exit code: \(.exit_code)", "stdout: \(.stdout | rtrimstr("\n"))"' [ "$(echo "$OUT" | jq -r '.stdout | rtrimstr("\n")')" = 42 ] || { echo "expected 42"; exit 1; } ``` TypeScript: ```typescript await client.sandboxes.runCode(sandbox.id, { language: 'python', code: 'x = 21 * 2' }); // One Python interpreter per sandbox: `x` is still defined in the next run. const run = await client.sandboxes.runCode(sandbox.id, { language: 'python', code: 'print(x)' }); console.log('outcome:', run.outcome, 'exit code:', run.exit_code); console.log('stdout:', run.stdout.trim()); if (run.stdout.trim() !== '42') throw new Error('expected 42'); ``` Python: ```python client.sandboxes.run_code(sandbox["id"], language="python", code="x = 21 * 2") # One Python interpreter per sandbox: `x` is still defined in the next run. run = client.sandboxes.run_code(sandbox["id"], language="python", code="print(x)") print("outcome:", run["outcome"], "exit code:", run["exit_code"]) print("stdout:", run["stdout"].strip()) assert run["stdout"].strip() == "42", "expected 42" ``` CLI: ```bash hayonix api sandboxes.runCode "$SANDBOX_ID" --param language=python --param code='x = 21 * 2' >/dev/null # One Python interpreter per sandbox: `x` is still defined in the next run. OUT=$(hayonix api sandboxes.runCode "$SANDBOX_ID" --param language=python --param code='print(x)' --json) echo "$OUT" | jq -r '"outcome: \(.outcome) exit code: \(.exit_code)", "stdout: \(.stdout | rtrimstr("\n"))"' [ "$(echo "$OUT" | jq -r '.stdout | rtrimstr("\n")')" = 42 ] || { echo "expected 42"; exit 1; } ``` The language decides what carries over from one run to the next: | Language | How it runs | What carries over | | python | One interpreter per sandbox; runs queue for it | Variables, imports and functions, and files | | javascript | A fresh Node process per run | Files | | shell | A fresh bash process per run | Files | Every run starts in /workspace, and files there persist for the sandbox's life whatever the language. Python comes with numpy, pandas, matplotlib, pillow and requests installed. Code is at most 256 KiB, and stdin (given to the code on standard input) at most 1 MiB. Up to 4 runs can be in progress in one sandbox at a time. ### The run record A run is queued, then running, then completed (it ran) or error (it could not run; error says why). A completed run has exit_code, stdout and stderr, and outcome sums it up in one word: succeeded, failed (a non-zero exit code), or the reason it was stopped. Each run has two limits you can set: - timeout_seconds: default 60, at most 900. - max_output_bytes: stdout and stderr together, default 1 MiB, at most 4 MiB. When a run is stopped before it finishes, cut_off says why: | cut_off | Meaning | | time_limit | It ran past timeout_seconds | | output_limit | It printed more than max_output_bytes | | out_of_memory | It ran out of memory | | cancelled | It was cancelled (POST …/runs/{run_id}/cancel) | | sandbox_ended | The sandbox ended while it ran | When a Python run ends with the interpreter gone (it crashed, ran out of memory, or had to be killed to stop at its limit), that run has state_reset: true: the next run starts a fresh interpreter, so variables from earlier runs are gone. Files are still there. The response to the run carries all of its output, up to its cap. The record kept afterwards (GET …/runs/{run_id}, GET …/runs) holds the first 64 KiB of each stream, and output.truncated says when that copy is shorter than what the run printed. Retries never run code twice: Running code is a creating call, so it takes an Idempotency-Key (the SDKs send one for you). A retry with the same key attaches to the first run instead of starting another. See Idempotency. ## Stream a run's output For a long run, ask for the run back at once with wait=false and follow its output as it is produced from GET /v1/sandboxes/{sandbox_id}/runs/{run_id}/events, a server-sent event stream. (stream=true on the run request answers with the same stream directly.) curl: ```bash # ?wait=false answers at once with the queued run; its events carry the output live. RUN_ID=$(run shell 'for i in 1 2 3; do echo "tick $i"; sleep 1; done' '?wait=false' | jq -r .id) # The stream ends after its `end` event; `output` events carry {stream, text}. EVENT="" curl -sS -N --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID/runs/$RUN_ID/events" -H "$AUTH" | while IFS= read -r line; do case "$line" in "event: "*) EVENT="${line#event: }" ;; "data: "*) if [ "$EVENT" = output ]; then printf '%s' "${line#data: }" | jq -j .text; fi ;; esac done curl -sS --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID/runs/$RUN_ID" -H "$AUTH" | jq -r '"streamed run: \(.outcome)"' ``` TypeScript: ```typescript // wait: 'false' answers at once with the queued run; its events carry the output live. const queued = await client.sandboxes.runCode(sandbox.id, { language: 'shell', code: 'for i in 1 2 3; do echo "tick $i"; sleep 1; done', wait: 'false', }); for await (const event of await client.sandboxes.streamRun(sandbox.id, queued.id)) { if (event.event === 'output') { const { text } = event.data as { stream: 'stdout' | 'stderr'; text: string }; process.stdout.write(text); } if (event.event === 'end') break; } const finished = await client.sandboxes.getRun(sandbox.id, queued.id); console.log('streamed run:', finished.outcome); ``` Python: ```python # wait="false" answers at once with the queued run; its events carry the output live. queued = client.sandboxes.run_code( sandbox["id"], language="shell", code='for i in 1 2 3; do echo "tick $i"; sleep 1; done', wait="false", ) with client.sandboxes.stream_run(sandbox["id"], queued["id"]) as events: for event in events: if event.event == "output": print(event.data["text"], end="", flush=True) if event.event == "end": break finished = client.sandboxes.get_run(sandbox["id"], queued["id"]) print("streamed run:", finished["outcome"]) ``` CLI: ```bash # wait=false answers at once with the queued run; streamRun prints its events, one JSON per line. RUN_ID=$(hayonix api sandboxes.runCode "$SANDBOX_ID" --param language=shell \ --param code='for i in 1 2 3; do echo "tick $i"; sleep 1; done' --param wait=false -q) hayonix api sandboxes.streamRun "$SANDBOX_ID" "$RUN_ID" | jq -j 'select(.event == "output") | .data.text' hayonix api sandboxes.getRun "$SANDBOX_ID" "$RUN_ID" --json | jq -r '"streamed run: \(.outcome)"' ``` The stream sends these events, in order: | Event | Data | | run | The run record, as it was when the stream opened | | started | started_at, once the run leaves the queue | | output | stream (stdout or stderr) and text, as the code prints it | | run | The finished run record | | end | The stream is over | A run's live output can be replayed from the start for an hour after the run ends; after that the stream sends the recorded output instead. ## Move files in and out Files live in the sandbox's workspace, /workspace. Every file route takes a path relative to it (data/numbers.csv; a leading /workspace/ is accepted too). A path containing .. is refused, so no path can reach outside the workspace. - PUT /v1/sandboxes/{sandbox_id}/files/content?path=… uploads a file as the multipart part file, replacing any file at that path and creating parent directories. - GET /v1/sandboxes/{sandbox_id}/files?path=… lists a directory. - GET /v1/sandboxes/{sandbox_id}/files/content?path=… downloads a file, streamed. - DELETE /v1/sandboxes/{sandbox_id}/files?path=… deletes a file, or a directory with everything in it. A file is at most 64 MiB each way, and the whole workspace shares the sandbox's disk. File operations count as activity for the idle timeout. curl: ```bash # Paths are relative to /workspace; parent directories are created. printf 'n\n1\n2\n3\n' > "$WORK/numbers.csv" curl -sS --fail-with-body -X PUT "$API_BASE_URL/sandboxes/$SANDBOX_ID/files/content?path=data/numbers.csv" \ -H "$AUTH" -F "file=@$WORK/numbers.csv" >/dev/null curl -sS --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID/files?path=data" -H "$AUTH" | jq -r '.data[] | "file: \(.path) \(.size) bytes"' run python 'import csv with open("data/numbers.csv") as f: print("sum:", sum(int(row["n"]) for row in csv.DictReader(f)))' | jq -r '.stdout | rtrimstr("\n")' curl -sS --fail-with-body "$API_BASE_URL/sandboxes/$SANDBOX_ID/files/content?path=data/numbers.csv" \ -H "$AUTH" -o "$WORK/downloaded.csv" echo "downloaded numbers.csv ($(wc -c < "$WORK/downloaded.csv") bytes)" cmp -s "$WORK/numbers.csv" "$WORK/downloaded.csv" || { echo "changed"; exit 1; } ``` TypeScript: ```typescript // Paths are relative to /workspace; parent directories are created. await client.sandboxes.uploadFile(sandbox.id, { path: 'data/numbers.csv', file: { name: 'numbers.csv', data: 'n\n1\n2\n3\n' }, }); const listing = await client.sandboxes.listFiles(sandbox.id, { path: 'data' }); for (const f of listing.data) console.log('file:', f.path, f.size, 'bytes'); const total = await client.sandboxes.runCode(sandbox.id, { language: 'python', code: [ 'import csv', "with open('data/numbers.csv') as f:", " print('sum:', sum(int(row['n']) for row in csv.DictReader(f)))", ].join('\n'), }); console.log(total.stdout.trim()); const download = await client.sandboxes.downloadFile(sandbox.id, { path: 'data/numbers.csv' }); const bytes = await download.saveTo('numbers.csv'); console.log(`downloaded numbers.csv (${bytes} bytes)`); if ((await readFile('numbers.csv', 'utf8')) !== 'n\n1\n2\n3\n') throw new Error('changed'); ``` Python: ```python # Paths are relative to /workspace; parent directories are created. client.sandboxes.upload_file( sandbox["id"], path="data/numbers.csv", file=("numbers.csv", b"n\n1\n2\n3\n"), ) listing = client.sandboxes.list_files(sandbox["id"], path="data") for f in listing["data"]: print("file:", f["path"], f["size"], "bytes") total = client.sandboxes.run_code( sandbox["id"], language="python", code="\n".join( [ "import csv", "with open('data/numbers.csv') as f:", " print('sum:', sum(int(row['n']) for row in csv.DictReader(f)))", ] ), ) print(total["stdout"].strip()) download = client.sandboxes.download_file(sandbox["id"], path="data/numbers.csv") size = download.save("numbers.csv") print(f"downloaded numbers.csv ({size} bytes)") with open("numbers.csv", "rb") as saved: assert saved.read() == b"n\n1\n2\n3\n", "changed" ``` CLI: ```bash # Paths are relative to /workspace; parent directories are created. printf 'n\n1\n2\n3\n' > "$WORK/numbers.csv" hayonix api sandboxes.uploadFile "$SANDBOX_ID" --param path=data/numbers.csv \ --param file="@$WORK/numbers.csv" >/dev/null hayonix api sandboxes.listFiles "$SANDBOX_ID" --param path=data --json | jq -r '.data[] | "file: \(.path) \(.size) bytes"' hayonix api sandboxes.runCode "$SANDBOX_ID" --param language=python --param code='import csv with open("data/numbers.csv") as f: print("sum:", sum(int(row["n"]) for row in csv.DictReader(f)))' --json | jq -r '.stdout | rtrimstr("\n")' hayonix api sandboxes.downloadFile "$SANDBOX_ID" --param path=data/numbers.csv -o "$WORK/downloaded.csv" cmp -s "$WORK/numbers.csv" "$WORK/downloaded.csv" || { echo "changed"; exit 1; } ``` ## End it curl: ```bash end_sandbox() { curl -sS --fail-with-body -X POST "$API_BASE_URL/sandboxes/$SANDBOX_ID/end" -H "$AUTH" | jq -r '"ended \(.id) \(.status.state)"' rm -rf "$WORK" } trap end_sandbox EXIT ``` TypeScript: ```typescript // Ending stops billing and deletes everything in the sandbox. const ended = await client.sandboxes.end(sandbox.id); console.log('ended', ended.id, ended.status.state); ``` Python: ```python # Ending stops billing and deletes everything in the sandbox. ended = client.sandboxes.end(sandbox["id"]) print("ended", ended["id"], ended["status"]["state"]) ``` CLI: ```bash end_sandbox() { hayonix api sandboxes.end "$SANDBOX_ID" --json | jq -r '"ended \(.id) \(.status.state)"' rm -rf "$WORK" } trap end_sandbox EXIT ``` ## Network A sandbox can reach the internet, so code can download packages and data. It can never reach the machine it runs on, the cloud provider's metadata service, the platform's control plane or anything belonging to another customer. Each project's sandboxes sit on a sandbox network of their own, apart from the project's pods. The platform never opens a port into a sandbox: code and files reach it only through the API. ## A key for an AI agent An agent that writes and runs code needs to reach sandboxes and nothing else. In the console, create an API key with only the Sandboxes scopes (sandbox:*: sandbox:read, sandbox:create, sandbox:update, sandbox:delete) and give the agent that key. It can create sandboxes, run code, move files, extend and end sandboxes in its project, and gets 403 for everything else, such as pods, secrets or models. See Projects and API keys. ## Next - Sandboxes API reference: every route and field. - Your first pod: a container that keeps running until you stop it, with the hardware you choose. --- # Evaluate outputs with a judge model URL: https://hayonix.ai/docs/quickstarts/evaluations Upload a dataset, have a judge model label, grade or compare every row, read the aggregate results and the rows that did not pass, and download the results file. An evaluation runs a judge model over every row of a dataset file. It works in one of three modes: | Mode | The judge gives each row | Results | | label | one label from label.choices (rows whose label is in label.passing pass) | how many rows got each label, pass rate | | grade | a number from grade.min to grade.max (rows at or above grade.passing_at pass) | mean, standard deviation, min, max, histogram, pass rate | | pairwise | the better of pairwise.a and pairwise.b, or a tie | A wins, B wins, ties, inconsistent pairs | What is judged — target for label and grade, pairwise.a and pairwise.b for pairwise — is either a column of the dataset ({"column": "answer"}) or text a model generates during the run from a prompt template ({"model": "…", "prompt": "Answer: {{question}}", "max_tokens": 256}). GET /v1/evaluations/models lists the models you can use as a judge or to generate. ## Upload a dataset A dataset is a JSON Lines file (one object per row; its keys are the columns) or a CSV file with a header row, uploaded with purpose evaluation. It is validated asynchronously: the file's validation report lists its rows and columns, and every problem with its line number. A file with problems cannot be evaluated. curl: ```bash # One JSON object per line; its keys are the columns templates can use. for review in "Absolutely wonderful, I loved every minute." \ "Broken on arrival and support never answered." "It arrived on Tuesday."; do jq -cn --arg review "$review" '{review: $review}' done > "$WORK/reviews.jsonl" DATASET_ID=$(curl -sS --fail-with-body "$API_BASE_URL/files" -H "$AUTH" \ -F purpose=evaluation -F "file=@$WORK/reviews.jsonl" | jq -r .id) until curl -sS --fail-with-body "$API_BASE_URL/files/$DATASET_ID" -H "$AUTH" | jq -e '.validation.state | IN("valid", "invalid")' >/dev/null; do sleep 1; done ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; // One JSON object per line; its keys are the columns templates can use. const reviews = [ 'Absolutely wonderful, I loved every minute.', 'Broken on arrival and support never answered.', 'It arrived on Tuesday.', ]; const dataset = await client.files.upload({ file: { name: 'reviews.jsonl', data: reviews.map((review) => JSON.stringify({ review })).join('\n') + '\n', }, purpose: 'evaluation', }); const validated = await client.waitFor.file(dataset.id); console.log('columns:', validated.validation.report?.dataset?.columns.join(', ')); ``` Python: ```python import json import os from hayonix import Client client = Client() model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") # One JSON object per line; its keys are the columns templates can use. reviews = [ "Absolutely wonderful, I loved every minute.", "Broken on arrival and support never answered.", "It arrived on Tuesday.", ] data = "".join(json.dumps({"review": r}) + "\n" for r in reviews) dataset = client.files.upload(file=("reviews.jsonl", data.encode()), purpose="evaluation") validated = client.wait_for.file(dataset["id"]) print("columns:", ", ".join(validated["validation"]["report"]["dataset"]["columns"])) ``` CLI: ```bash for review in "Absolutely wonderful, I loved every minute." \ "Broken on arrival and support never answered." "It arrived on Tuesday."; do jq -cn --arg review "$review" '{review: $review}' done > reviews.jsonl DATASET_ID=$(hayonix files upload reviews.jsonl --purpose evaluation --wait -q) ``` ## Estimate the cost The estimate takes the same settings as creating an evaluation and checks them the same way: a {{column}} placeholder that names a column the dataset does not have is an error that names the column, before anything is spent. It returns the most the run can cost and the first row's requests exactly as they will be sent. curl: ```bash jq -n --arg file "$DATASET_ID" --arg model "$MODEL" '{ mode: "label", dataset_file_id: $file, judge: {model: $model, instructions: "Classify the sentiment of this customer review.", max_tokens: 200}, target: {column: "review"}, label: {choices: ["positive", "negative", "neutral"], passing: ["positive"]} }' > "$WORK/settings.json" curl -sS --fail-with-body "$API_BASE_URL/evaluations/estimate" -H "$AUTH" \ -H "Content-Type: application/json" -d @"$WORK/settings.json" | jq -r '"at most \(.max_cost) nano-USD for \(.planned_calls) calls"' ``` TypeScript: ```typescript const settings = { mode: 'label' as const, dataset_file_id: dataset.id, judge: { model, instructions: 'Classify the sentiment of this customer review.', max_tokens: 200, }, target: { column: 'review' }, label: { choices: ['positive', 'negative', 'neutral'], passing: ['positive'] }, }; const estimate = await client.evaluations.estimate(settings); console.log(`at most ${estimate.max_cost} nano-USD for ${estimate.planned_calls} calls`); ``` Python: ```python settings = { "mode": "label", "dataset_file_id": dataset["id"], "judge": { "model": model, "instructions": "Classify the sentiment of this customer review.", "max_tokens": 200, }, "target": {"column": "review"}, "label": {"choices": ["positive", "negative", "neutral"], "passing": ["positive"]}, } estimate = client.evaluations.estimate(**settings) print(f"at most {estimate['max_cost']} nano-USD for {estimate['planned_calls']} calls") ``` CLI: ```bash SETTINGS=(--dataset "$DATASET_ID" --mode label --judge "$MODEL" --instructions "Classify the sentiment of this customer review." --judge-max-tokens 200 --column review --labels positive,negative,neutral --passing positive) hayonix evaluations estimate "${SETTINGS[@]}" ``` Every model call is an ordinary inference request charged at the model's batch price as it completes, and runs at low priority behind live traffic; nothing is reserved up front. The estimate is an upper bound: input tokens are counted as at most the UTF-8 bytes of each request, output tokens as max_tokens. A judge answer that cannot be read is asked again (at most 3 calls per judging step); those retries are charged like any call and are not in the estimate. ## Create it and wait An evaluation is validating, then running and finalizing, and ends completed, stopped (it ran out of credit or time, and kept every row it finished), failed (the dataset could not be evaluated, or more than half of the rows errored) or cancelled. curl: ```bash EVALUATION_ID=$(curl -sS --fail-with-body "$API_BASE_URL/evaluations" -H "$AUTH" \ -H "Content-Type: application/json" -d @"$WORK/settings.json" | jq -r .id) while :; do EVALUATION=$(curl -sS --fail-with-body "$API_BASE_URL/evaluations/$EVALUATION_ID" -H "$AUTH") STATUS=$(echo "$EVALUATION" | jq -r .status) echo "status: $STATUS" case "$STATUS" in completed|stopped|failed|cancelled) break ;; esac sleep 3 done ``` TypeScript: ```typescript const evaluation = await client.evaluations.create({ name: 'review sentiment', ...settings }); const done = await client.waitFor.evaluation(evaluation.id, { onUpdate: (e) => { console.log('status:', e.status); }, }); ``` Python: ```python evaluation = client.evaluations.create(name="review sentiment", **settings) done = client.wait_for.evaluation(evaluation["id"], on_update=lambda e: print("status:", e["status"])) ``` CLI: ```bash EVALUATION_ID=$(hayonix evaluations create "${SETTINGS[@]}" --name "review sentiment" -q) until platform evaluations show "$EVALUATION_ID" --json | jq -e '.status | IN("completed", "stopped", "failed", "cancelled")' >/dev/null; do sleep 3 done hayonix evaluations show "$EVALUATION_ID" ``` In pairwise mode each pair is judged twice, once with each candidate shown first, and a win counts only when both passes agree; pairs where they disagree are counted as inconsistent, so the judge's position bias does not pass for a result. ## Read the results results holds the aggregate numbers (while the run is going, too). GET /v1/evaluations/{evaluation_id}/rows lists the rows in dataset order with the verdict, the judge's reasoning, the texts and the cost; filter narrows it to passed, failed, errored (rows with an error, and rows never run) or inconsistent. curl: ```bash echo "$EVALUATION" | jq -r '"pass rate: \(.results.pass_rate * 100)%"' curl -sS --fail-with-body "$API_BASE_URL/evaluations/$EVALUATION_ID/rows?filter=failed" -H "$AUTH" | jq -r '.data[] | "row \(.row): \(.verdict.label) (\(.reasoning))"' ``` TypeScript: ```typescript if (done.status !== 'completed' || !done.results) throw new Error(`evaluation ${done.status}`); for (const l of done.results.labels ?? []) console.log(`${l.label}: ${l.count}`); console.log(`pass rate: ${((done.results.pass_rate ?? 0) * 100).toFixed(1)}%`); // The rows that did not pass, with the judge's reasoning. for await (const row of client.evaluations.listRows(done.id, { filter: 'failed' })) console.log(`row ${row.row}: ${row.verdict?.label} (${row.reasoning})`); ``` Python: ```python if done["status"] != "completed" or not done["results"]: raise SystemExit(f"evaluation {done['status']}") for label in done["results"]["labels"] or []: print(f"{label['label']}: {label['count']}") print(f"pass rate: {(done['results']['pass_rate'] or 0) * 100:.1f}%") # The rows that did not pass, with the judge's reasoning. for row in client.evaluations.list_rows(done["id"], filter="failed"): print(f"row {row['row']}: {row['verdict']['label']} ({row['reasoning']})") ``` CLI: ```bash hayonix evaluations show "$EVALUATION_ID" --json | jq -r '"pass rate: \(.results.pass_rate * 100)%"' hayonix evaluations rows "$EVALUATION_ID" --filter failed ``` The judge's answer is constrained to a JSON schema and parsed strictly. A row whose answer still cannot be read after the last try is an error row with the reason; a verdict is never guessed. ## Download the results file result_file_id is a JSON Lines file (purpose evaluation_results) with one line per row: the inputs the run used, the generated texts, the verdict and reasoning, every judge answer, tokens, cost and any error. It is kept for 30 days. curl: ```bash curl -sS --fail-with-body "$API_BASE_URL/files/$RESULT_ID/content" -H "$AUTH" | jq -r '"row \(.row): \(.status) \(.verdict.label // "")"' ``` TypeScript: ```typescript // One JSON line per row: inputs, generated text, verdict, reasoning, tokens, cost, error. if (done.result_file_id) { const file = await client.files.getContent(done.result_file_id); for (const line of (await file.text()).trim().split('\n')) { const r = JSON.parse(line) as { row: number; status: string; verdict: { label?: string } }; console.log(`row ${r.row}: ${r.status} ${r.verdict.label ?? ''}`); } } ``` Python: ```python # One JSON line per row: inputs, generated text, verdict, reasoning, tokens, cost, error. if done.get("result_file_id"): content = client.files.get_content(done["result_file_id"]) for line in content.text().strip().splitlines(): r = json.loads(line) print(f"row {r['row']}: {r['status']} {(r['verdict'] or {}).get('label', '')}") ``` CLI: ```bash hayonix files download "$RESULT_ID" -o - | jq -r '"row \(.row): \(.status) \(.verdict.label // "")"' ``` --- # Serve HTTP from a serverless endpoint URL: https://hayonix.ai/docs/quickstarts/http-endpoints Run an image that serves HTTP itself behind a stable URL, scale it with requests in flight down to zero, roll releases without failed requests, and keep idle workers paused so the next request skips the cold start. A serverless endpoint is one of two types, chosen when you create it: | Type | Callers | Your image | Fits | | queue | submit jobs and fetch the results, or wait for them | runs a handler on the worker runtime | batch work, long jobs, retries, webhooks | | http | send HTTP requests to the endpoint's URL | serves HTTP itself, unchanged | existing servers (an OpenAI-compatible model server, say), streaming, WebSockets, low latency | This guide is about http endpoints. Your image needs only to listen on a port and answer a health path with a 2xx or 3xx once it is ready; no platform runtime is involved. ## Create one http.port is where your server listens inside the container; http.health_path is probed with GET before a worker takes requests, and keeps being probed: a worker that fails it is taken out of rotation, and replaced if it does not recover within 30 s. concurrency is the most requests one worker serves at once. The response carries the endpoint's url. curl: ```bash ENDPOINT=$( jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "http-server", mode: "http", image: $image, http: { port: 8000, health_path: "/health" }, skus: [$sku], region: $region, concurrency: 8, max_workers: 2, cold_start_wait_seconds: 120 }' | curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints" \ -H "$AUTH" -H "Content-Type: application/json" -d @- ) ENDPOINT_ID=$(echo "$ENDPOINT" | jq -r .id) URL=$(echo "$ENDPOINT" | jq -r .url) echo "endpoint $ENDPOINT_ID at $URL" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const image = process.env.IMAGE ?? 'registry.example.com/team/http-server:1.0.0'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const endpoint = await client.serverless.createEndpoint({ name: 'http-server', mode: 'http', image, http: { port: 8000, health_path: '/health' }, skus: [sku], region, concurrency: 8, max_workers: 2, cold_start_wait_seconds: 120, }); const url = endpoint.url ?? ''; console.log('endpoint', endpoint.id, 'at', url); ``` Python: ```python import json import os import httpx from hayonix import Client client = Client() image = os.environ.get("IMAGE", "registry.example.com/team/http-server:1.0.0") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") endpoint = client.serverless.create_endpoint( name="http-server", mode="http", image=image, http={"port": 8000, "health_path": "/health"}, skus=[sku], region=region, concurrency=8, max_workers=2, cold_start_wait_seconds=120, ) url = endpoint["url"] print("endpoint", endpoint["id"], "at", url) ``` CLI: ```bash ENDPOINT_ID=$(hayonix serverless create --name http-server --mode http --image "$IMAGE" \ --http-port 8000 --health-path /health --sku "$SKU" --region "$REGION" \ --concurrency 8 --max-workers 2 --cold-start-wait 120 -q) URL=$(hayonix serverless show "$ENDPOINT_ID" --json | jq -r .url) echo "endpoint $ENDPOINT_ID at $URL" ``` ## Call it Send any method and path to the URL with an API key of the endpoint's project that holds the Serverless endpoints invoke permission (serverless_endpoint:invoke) as Authorization: Bearer. Without a key the answer is 401; a key of another project gets 404, as if the endpoint did not exist. curl: ```bash # Any method and path reaches your server. With no worker running, this waits for one to # start (up to cold_start_wait_seconds), then answers. curl -sS --fail-with-body "${URL}" -H "$AUTH" | jq -r '"answered by \(.worker_id)"' # Streaming responses arrive as they are written (-N turns off curl's buffering). curl -sSN --fail-with-body "${URL}stream?n=3&delay=0.2" -H "$AUTH" | sed -n 's/^data: \(.*\)/\1/p' | jq -r '"event \(.i)"' ``` TypeScript: ```typescript // Plain fetch with an API key of the project; the key never reaches your container. const headers = { Authorization: `Bearer ${process.env.API_KEY ?? ''}` }; const res = await fetch(url, { headers }); if (!res.ok) throw new Error(`${String(res.status)}: ${await res.text()}`); const who = (await res.json()) as { worker_id: string }; console.log('answered by', who.worker_id); // A streamed response, read as it arrives. const stream = await fetch(`${url}stream?n=3&delay=0.2`, { headers }); const decoder = new TextDecoder(); let buffer = ''; for await (const part of stream.body ?? []) { buffer += decoder.decode(part, { stream: true }); let end; while ((end = buffer.indexOf('\n\n')) !== -1) { const event = buffer.slice(0, end).replace(/^data: /, ''); buffer = buffer.slice(end + 2); console.log('event', (JSON.parse(event) as { i: number }).i); } } ``` Python: ```python # Plain httpx with an API key of the project; the key never reaches your container. headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"} with httpx.Client(headers=headers, timeout=180) as http: res = http.get(url) res.raise_for_status() print("answered by", res.json()["worker_id"]) # A streamed response, read as it arrives. with http.stream("GET", f"{url}stream", params={"n": 3, "delay": 0.2}) as stream: for line in stream.iter_lines(): if line.startswith("data: "): print("event", json.loads(line[6:])["i"]) ``` CLI: ```bash # The first request waits for a worker to start, then answers. curl -sS --fail-with-body "$URL" -H "Authorization: Bearer $API_KEY" | jq -r '"answered by \(.worker_id)"' curl -sSN --fail-with-body "${URL}stream?n=3&delay=0.2" -H "Authorization: Bearer $API_KEY" | sed -n 's/^data: \(.*\)/\1/p' | jq -r '"event \(.i)"' ``` What your container receives: - the request as sent, streamed in both directions: server-sent events, chunked responses and WebSocket upgrades pass through as they are written. Request bodies are limited to 100 MiB. - never the platform API key or console cookies. Instead: x-endpoint-caller-key-id (the ID of the key that called, to tell callers apart), x-endpoint-request-id (also returned to the caller), x-endpoint-id and x-endpoint-worker-id, and X-Forwarded-For/-Proto/-Host. Headers starting with x-endpoint- that a caller sends are dropped. - the environment variables WORKER_RUNTIME_PORT, WORKER_RUNTIME_WORKER_ID, WORKER_RUNTIME_ENDPOINT_ID and WORKER_RUNTIME_RELEASE_ID, besides your own. ## Scaling and cold starts Workers are added and removed to keep about scaling.target requests in flight per worker (requests waiting for a worker count too), between min_workers and max_workers. A request goes to the worker with the fewest requests in flight, never to one already at its concurrency. With no worker ready — the endpoint scaled to zero, or every worker busy — a request waits for one for up to cold_start_wait_seconds (default 60, at most 300) while the autoscaler starts one. If none is ready in time it is answered 503 with code no_worker_ready (or workers_busy) and a Retry-After header: retry it. When the organization cannot start a worker at all (out of credit, suspended, at a spend limit), the answer is the matching error at once — 402 for no credit — not a timeout. A worker leaves rotation before it is removed (scaling down, or replaced by a new release) and gets drain_timeout_seconds to finish the requests it has in flight. A response must start within execution_timeout_seconds; after that it is answered 504. Long streams and WebSockets may then run as long as data keeps moving. ## Releases Changing the image, environment, hardware, concurrency or http settings makes a new release. New workers start on it and must pass their health check before workers of the old release leave rotation, so a release rolls out without a failed request. Rolling back makes a new release with an earlier spec. ## Fast resume An idle worker is normally removed after idle_timeout_seconds, and the next request pays for a cold start (starting the container and, typically, loading a model). With fast_resume.max_paused_workers above 0, up to that many idle workers are paused instead: the container is frozen in place with its memory — and its loaded model, on a GPU its VRAM — intact, and the next request (or job, on a queue endpoint) resumes it in a fraction of a cold start. A paused worker is removed after fast_resume.paused_keep_seconds. curl: ```bash # Keep one idle worker paused instead of removing it: the next request resumes it in a # fraction of a cold start. Paused time is not charged. curl -sS --fail-with-body -X PATCH "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID" \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"fast_resume": {"max_paused_workers": 1, "paused_keep_seconds": 600}}' | jq -r '"fast resume: \(.fast_resume.max_paused_workers) paused worker kept"' ``` TypeScript: ```typescript // Keep one idle worker paused instead of removing it; paused time is not charged. const updated = await client.serverless.updateEndpoint(endpoint.id, { fast_resume: { max_paused_workers: 1, paused_keep_seconds: 600 }, }); console.log('fast resume:', updated.fast_resume.max_paused_workers, 'paused worker kept'); ``` Python: ```python # Keep one idle worker paused instead of removing it; paused time is not charged. updated = client.serverless.update_endpoint( endpoint["id"], fast_resume={"max_paused_workers": 1, "paused_keep_seconds": 600} ) print("fast resume:", updated["fast_resume"]["max_paused_workers"], "paused worker kept") ``` CLI: ```bash hayonix serverless update "$ENDPOINT_ID" --paused-workers 1 --paused-keep 600 --json | jq -r '"fast resume: \(.fast_resume.max_paused_workers) paused worker kept"' ``` What it costs: nothing while paused. Billing is per second of running time, and paused seconds are not counted (a resumed worker bills again from the moment it is unfrozen). In exchange, the platform may remove a paused worker at any time when its host needs the capacity; the next request then starts a new worker, as without fast resume. Paused workers do not count against your worker quota. Fast resume works the same way on queue endpoints. The endpoint's metrics show cold starts and resumes separately (GET /v1/serverless/endpoints/{endpoint_id}/metrics), and GET …/request-metrics has the request rate, status classes, latency percentiles, requests in flight and how often a request waited for a worker, per endpoint and per worker. ## Delete it curl: ```bash delete_endpoint() { curl -sS --fail-with-body -X DELETE "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID" \ -H "$AUTH" >/dev/null echo "deleted $ENDPOINT_ID" } trap delete_endpoint EXIT ``` TypeScript: ```typescript await client.serverless.deleteEndpoint(endpoint.id); console.log('deleted', endpoint.id); ``` Python: ```python client.serverless.delete_endpoint(endpoint["id"]) print("deleted", endpoint["id"]) ``` CLI: ```bash trap 'platform serverless delete "$ENDPOINT_ID" -y && echo "deleted $ENDPOINT_ID"' EXIT ``` --- # Run a multi-node job on a cluster URL: https://hayonix.ai/docs/quickstarts/clusters Create identical members on one private network across hosts, all at once or not at all, reach the head over SSH, start processes on every member with the launcher, run torchrun or mpirun across them, and share files on a shared volume. A cluster is a fixed number of identical members — same image, same hardware — placed on one private network that spans hosts, for one distributed job: multi-node training, an MPI program, a parameter sweep. Member 0 is the head. Every member gets a fixed private address and a hostname, member- (the head is also head), that resolves on every member, and the environment variables that launchers such as torchrun and mpirun need. An optional shared volume is mounted read-write at the same path on every member. ## Before you start - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 The samples read IMAGE, SKU and REGION. A cluster has 2 to 16 members. The organization's clusters, cluster_members and gpus quotas apply (see Quotas and limits). An API key needs the cluster:* scopes. ## What it costs GET /v1/clusters/estimate prices a shape at today's prices. Each member is billed per second from the start of its run, like a pod, at its hardware's price, until its container stops; a member waiting to start is not billed. The shared volume is billed per GB-second for as long as the cluster exists, until it is deleted. See How compute is billed. curl: ```bash curl -sS --fail-with-body -G "$API_BASE_URL/clusters/estimate" -H "$AUTH" \ --data-urlencode "sku=$SKU" -d member_count=2 -d shared_volume_gb=10 | jq -r '"total per hour (nano-USD): \(.total_per_hour)"' ``` TypeScript: ```typescript import { Client, ConflictError } from 'hayonix'; const client = new Client(); const image = process.env.IMAGE ?? 'busybox:1.37.0'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const estimate = await client.clusters.estimate({ sku, member_count: 2, shared_volume_gb: 10, }); console.log('total per hour (nano-USD):', estimate.total_per_hour); ``` Python: ```python import os import sys import time from hayonix import Client, ConflictError client = Client() image = os.environ.get("IMAGE", "busybox:1.37.0") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") estimate = client.clusters.estimate(sku=sku, member_count=2, shared_volume_gb=10) print("total per hour (nano-USD):", estimate["total_per_hour"]) ``` CLI: ```bash hayonix clusters estimate --sku "$SKU" --members 2 --shared-volume-gb 10 ``` ## Create a cluster Every member is placed on a host before the request returns, or nothing is: if any member does not fit — not enough free hosts, CPUs, memory or GPUs in the region — the request fails with 409 and code insufficient_capacity, and nothing is created or billed. Clusters never preempt other work. Members are spread over hosts first, and may share a host when the region has room for several on one. curl: ```bash # Every member runs the same command; this one prints where it is and stays up. COMMAND='echo "rank=$CLUSTER_RUNTIME_RANK of $CLUSTER_RUNTIME_SIZE host=$CLUSTER_RUNTIME_HOSTNAME head=$CLUSTER_RUNTIME_HEAD_ADDRESS"; exec sleep infinity' if ! CLUSTER=$( jq -n --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" --arg cmd "$COMMAND" '{ name: "guide", member_count: 2, hardware: { sku: $sku, gpu_count: 0 }, region: $region, image: $image, command: ["sh", "-c", $cmd], shared_volume: { size_gb: 10, mount_path: "/shared" } }' | curl -sS --fail-with-body "$API_BASE_URL/clusters" \ -H "$AUTH" -H "Content-Type: application/json" -d @- ); then # All or nothing: a 409 insufficient_capacity means nothing was created or billed. echo "$CLUSTER" | jq -r '"not created: \(.error.code): \(.error.message)"' exit 1 fi CLUSTER_ID=$(echo "$CLUSTER" | jq -r .id) echo "created $CLUSTER_ID $(echo "$CLUSTER" | jq -r .state)" ``` TypeScript: ```typescript let cluster; try { cluster = await client.clusters.create({ name: 'guide', member_count: 2, // member 0 is the head hardware: { sku, gpu_count: 0 }, region, image, // Every member runs the same command; this one prints where it is and stays up. command: [ 'sh', '-c', 'echo "rank=$CLUSTER_RUNTIME_RANK of $CLUSTER_RUNTIME_SIZE host=$CLUSTER_RUNTIME_HOSTNAME head=$CLUSTER_RUNTIME_HEAD_ADDRESS"; exec sleep infinity', ], shared_volume: { size_gb: 10, mount_path: '/shared' }, }); } catch (err) { // All or nothing: if one member does not fit, nothing is created or billed. if (err instanceof ConflictError && err.code === 'insufficient_capacity') { console.log('not created:', err.message); process.exit(1); } throw err; } console.log('created', cluster.id, cluster.state); ``` Python: ```python try: cluster = client.clusters.create( name="guide", member_count=2, # member 0 is the head hardware={"sku": sku, "gpu_count": 0}, region=region, image=image, # Every member runs the same command; this one prints where it is and stays up. command=[ "sh", "-c", 'echo "rank=$CLUSTER_RUNTIME_RANK of $CLUSTER_RUNTIME_SIZE host=$CLUSTER_RUNTIME_HOSTNAME' ' head=$CLUSTER_RUNTIME_HEAD_ADDRESS"; exec sleep infinity', ], shared_volume={"size_gb": 10, "mount_path": "/shared"}, ) except ConflictError as err: # All or nothing: if one member does not fit, nothing is created or billed. if err.code != "insufficient_capacity": raise print("not created:", err.message) sys.exit(1) print("created", cluster["id"], cluster["state"]) ``` CLI: ```bash # Every member runs the same command; this one prints where it is and stays up. --wait returns # once every member runs, and fails if one fails first. A cluster that does not fit fails with # insufficient_capacity, and nothing is created. COMMAND='echo "rank=$CLUSTER_RUNTIME_RANK of $CLUSTER_RUNTIME_SIZE host=$CLUSTER_RUNTIME_HOSTNAME head=$CLUSTER_RUNTIME_HEAD_ADDRESS"; exec sleep infinity' CLUSTER_ID=$(hayonix clusters create --name guide --members 2 --sku "$SKU" --region "$REGION" \ --image "$IMAGE" --command "$(jq -cn --arg cmd "$COMMAND" '["sh", "-c", $cmd]')" \ --shared-volume-gb 10 --mount-path /shared --wait -q) echo "created $CLUSTER_ID" ``` command replaces the image's entrypoint on every member; an image whose command exits makes its member failed, so for interactive work keep the members up (sleep infinity, a notebook, an SSH-ready image) and start your job from the head. A cluster's configuration never changes after creation: only its name can (PATCH /v1/clusters/{cluster_id}). ## Wait until every member runs The cluster is provisioning while members pull their image and start, and running once every member's container runs. GET /v1/clusters/{cluster_id} lists every member with its rank, hostname, private address, state and host (host_id is opaque; members with the same value share a host), and the ready-to-run ssh command for each. curl: ```bash # provisioning → running once every member runs; degraded means one failed (nothing restarts it). while STATE=$(curl -sS --fail-with-body "$API_BASE_URL/clusters/$CLUSTER_ID" -H "$AUTH" | jq -r .state) [ "$STATE" = provisioning ]; do sleep 3; done [ "$STATE" = running ] || { echo "cluster is $STATE"; exit 1; } curl -sS --fail-with-body "$API_BASE_URL/clusters/$CLUSTER_ID" -H "$AUTH" | jq -r '.members[] | "member \(.rank): \(.hostname) \(.address) \(.state)", (select(.rank == 0) | "ssh to the head: \(.ssh.command)")' ``` TypeScript: ```typescript // Until every member runs; throws if one fails first (the cluster becomes `degraded`). const running = await client.waitFor.cluster(cluster.id); for (const m of running.members) console.log(`member ${String(m.rank)}: ${m.hostname} ${m.address} ${m.state}`); console.log('ssh to the head:', running.members[0]?.ssh?.command); ``` Python: ```python # Until every member runs; raises if one fails first (the cluster becomes `degraded`). running = client.wait_for.cluster(cluster["id"]) for m in running["members"]: print(f"member {m['rank']}: {m['hostname']} {m['address']} {m['state']}") head_ssh = running["members"][0]["ssh"] print("ssh to the head:", head_ssh["command"] if head_ssh else None) ``` CLI: ```bash hayonix clusters get "$CLUSTER_ID" # every rank: hostname, address, state, host hayonix clusters ssh "$CLUSTER_ID" # the head's ssh command (--rank N for another member) ``` ## Connect to the head Members are reached through the platform's SSH gateway with one of the project's SSH keys (hayonix ssh-keys add ~/.ssh/id_ed25519.pub, or the console). Run the head's ssh.command; hayonix clusters ssh prints it (--rank N for another member, --known-hosts for lines that pin the gateway's host keys). Nothing in the image needs to run an SSH server. ## The rank and host environment Every member has these variables, set by the platform (customers cannot set names starting with CLUSTER_RUNTIME_): | Variable | Value | | CLUSTER_RUNTIME_CLUSTER_ID | The cluster's ID | | CLUSTER_RUNTIME_RANK | This member's rank, 0 on the head | | CLUSTER_RUNTIME_SIZE | Number of members | | CLUSTER_RUNTIME_HOSTNAME, CLUSTER_RUNTIME_ADDRESS | This member's hostname (member-) and private address | | CLUSTER_RUNTIME_HEAD_HOSTNAME, CLUSTER_RUNTIME_HEAD_ADDRESS | The head's | | CLUSTER_RUNTIME_HOSTNAMES | Every hostname in rank order, separated by spaces | | CLUSTER_RUNTIME_HOSTS | member-0=
,member-1=
,… in rank order | | CLUSTER_RUNTIME_GPUS_PER_MEMBER | GPUs on each member (0 on CPU hardware) | | CLUSTER_RUNTIME_LAUNCHER | The launcher (below) | | CLUSTER_RUNTIME_SHARED_PATH | Where the shared volume is mounted, when there is one | On a member: ```bash # (CLUSTER_RUNTIME_SSH_KEY is the key members use to reach each other: keep it out of logs.) env | grep '^CLUSTER_RUNTIME_' | grep -v '^CLUSTER_RUNTIME_SSH_KEY=' | sort # CLUSTER_RUNTIME_ADDRESS=10.224.5.2 # CLUSTER_RUNTIME_CLUSTER_ID=clu_01jc… # CLUSTER_RUNTIME_GPUS_PER_MEMBER=0 # CLUSTER_RUNTIME_HEAD_ADDRESS=10.224.5.2 # CLUSTER_RUNTIME_HEAD_HOSTNAME=member-0 # CLUSTER_RUNTIME_HOSTNAME=member-0 # CLUSTER_RUNTIME_HOSTNAMES=member-0 member-1 # CLUSTER_RUNTIME_HOSTS=member-0=10.224.5.2,member-1=10.224.5.3 # CLUSTER_RUNTIME_LAUNCHER=/.nodeagent/member-ssh # CLUSTER_RUNTIME_RANK=0 # CLUSTER_RUNTIME_SHARED_PATH=/shared # CLUSTER_RUNTIME_SIZE=2 ``` Addresses and hostnames are fixed for the cluster's life. On the private network a member reaches the cluster's own members and nothing else: not other clusters' members, not other projects' pods, not the hosts. ## Run a command on every member $CLUSTER_RUNTIME_LAUNCHER starts a process on another member. It takes ssh's arguments — a host, then the command — and returns the command's output and exit code as ssh would, so it works wherever a tool expects an ssh-compatible launcher. Nothing has to be installed, no keys exchanged, no SSH server configured. On the head: ```bash # The launcher takes ssh's arguments: a host, then the command. Its exit code and stderr come back # as ssh would return them. Nothing to install or configure in the image. $CLUSTER_RUNTIME_LAUNCHER member-1 hostname for h in $CLUSTER_RUNTIME_HOSTNAMES; do $CLUSTER_RUNTIME_LAUNCHER "$h" "hostname; nproc" done ``` ## Multi-node PyTorch with torchrun Start one torchrun per member: --nnodes=$CLUSTER_RUNTIME_SIZE, --node_rank the member's rank, and the rendezvous on the head with --master_addr=$CLUSTER_RUNTIME_HEAD_ADDRESS. Use the gloo backend on CPU members and nccl on GPU members. Create the cluster with GLOO_SOCKET_IFNAME=eth0 (and NCCL_SOCKET_IFNAME=eth0 on GPUs) in its env, so the backends use the private network's interface. The image must have PyTorch. The training script, on the shared volume: ```bash # On the shared volume, so every member runs the same file. cat > "$CLUSTER_RUNTIME_SHARED_PATH/ddp.py" <<'EOF' import os import socket import torch import torch.distributed as dist gpu = torch.cuda.is_available() if gpu: torch.cuda.set_device(int(os.environ["LOCAL_RANK"])) dist.init_process_group("nccl" if gpu else "gloo") rank, world = dist.get_rank(), dist.get_world_size() t = torch.tensor([float(rank + 1)], device="cuda" if gpu else "cpu") dist.all_reduce(t) print(f"rank={rank} world={world} host={socket.gethostname()} sum={t.item():.0f}", flush=True) dist.destroy_process_group() EOF ``` On the head: ```bash # One torchrun per member: --node_rank is the member's rank, the rendezvous is on the head. NPROC=$((CLUSTER_RUNTIME_GPUS_PER_MEMBER > 0 ? CLUSTER_RUNTIME_GPUS_PER_MEMBER : 1)) run_member() { # run_member RANK: the torchrun command line for that member echo "cd $CLUSTER_RUNTIME_SHARED_PATH && torchrun --nnodes=$CLUSTER_RUNTIME_SIZE" \ "--node_rank=$1 --nproc_per_node=$NPROC" \ "--master_addr=$CLUSTER_RUNTIME_HEAD_ADDRESS --master_port=29500 ddp.py" } # Every other member, in the background, through the launcher (output kept on the shared volume)… for R in $(seq 1 $((CLUSTER_RUNTIME_SIZE - 1))); do $CLUSTER_RUNTIME_LAUNCHER "member-$R" "$(run_member "$R")" \ > "$CLUSTER_RUNTIME_SHARED_PATH/rank-$R.log" 2>&1 & done # …and the head itself, in the foreground. sh -c "$(run_member "$CLUSTER_RUNTIME_RANK")" wait cat "$CLUSTER_RUNTIME_SHARED_PATH"/rank-*.log # rank=0 world=2 host=member-0 sum=3 # rank=1 world=2 host=member-1 sum=3 ``` ## MPI with mpirun mpirun starts its daemons on other hosts over ssh; point it at the launcher instead with --mca plm_rsh_agent $CLUSTER_RUNTIME_LAUNCHER, and give it a hostfile built from $CLUSTER_RUNTIME_HOSTNAMES. Every member must have the same MPI build, which it does when the image has one. On the head: ```bash # A hostfile from the member list: one line per member, one slot per GPU (or one on CPU). SLOTS=$((CLUSTER_RUNTIME_GPUS_PER_MEMBER > 0 ? CLUSTER_RUNTIME_GPUS_PER_MEMBER : 1)) for h in $CLUSTER_RUNTIME_HOSTNAMES; do echo "$h slots=$SLOTS"; done > hostfile # mpirun starts its daemons on the other members through the launcher instead of ssh. mpirun --mca plm_rsh_agent "$CLUSTER_RUNTIME_LAUNCHER" --hostfile hostfile \ -np $((CLUSTER_RUNTIME_SIZE * SLOTS)) hostname ``` ## The shared volume With shared_volume, one volume is mounted read-write at mount_path (default /shared) on every member, with the same files everywhere: a place for code, datasets, checkpoints and logs that every rank reads. On the head: ```bash # The same files on every member: write on one, read on another. echo "written on $CLUSTER_RUNTIME_HOSTNAME" > "$CLUSTER_RUNTIME_SHARED_PATH/hello.txt" $CLUSTER_RUNTIME_LAUNCHER member-1 cat "$CLUSTER_RUNTIME_SHARED_PATH/hello.txt" ``` What the shared volume is, and is not: The data lives on one host: the head's (shared_volume.served_by_rank is 0), and the other members reach it over the cluster's encrypted network between hosts. So: - If the head's host is lost, the volume is unavailable: on the other members, reads and writes to it fail with an error (ETIMEDOUT) after about two minutes, and data written and not yet synced may be lost. The cluster then reads degraded with reason shared_volume_unavailable. A shorter interruption of the network between hosts is ridden out. Keep anything you cannot lose (final checkpoints, results) somewhere else as well. - Throughput from other members is bounded by that network: about 125 MB/s measured between two development hosts on one machine. On real hosts it has not been measured yet. - It holds no more than its size (size_gb, in GiB), on every member alike: a write past it fails with "No space left on device" (ENOSPC), from the head and from the other members. Data written past the size is not kept. On a member other than the head, deleting the file whose write was just refused can take a few seconds, or fail with the same error for that long (up to about 11 s measured), while that member still holds the data the volume refused; retry the delete and it succeeds. The space used is measured on the head's host and shown as usage on the volume and on the Volumes page. - Its data is destroyed when the cluster is deleted. ## Degraded clusters A member whose container exits or cannot start becomes failed; one whose host stops answering becomes host_lost. Either makes the cluster degraded (state_reason member_failed or host_lost). Nothing is restarted or replaced: the other members keep running — and billing — until you delete the cluster, because a distributed job has usually lost its group by then anyway. A member on a lost host stops being billed at the last second its host proved it was running. The timeline says which member and why. curl: ```bash curl -sS --fail-with-body "$API_BASE_URL/clusters/$CLUSTER_ID/events" -H "$AUTH" | jq -r '.data[] | "event: \(.type) \(.message)"' ``` TypeScript: ```typescript for (const e of (await client.clusters.listEvents(cluster.id)).data) console.log('event:', e.type, e.message); ``` Python: ```python for e in client.clusters.list_events(cluster["id"]): print("event:", e["type"], e["message"]) ``` CLI: ```bash hayonix clusters events "$CLUSTER_ID" ``` A cluster can also be stopped by the platform (the organization ran out of credit, or a host was drained for maintenance): every member stops and only deletion remains. ## A member's output GET /v1/clusters/{cluster_id}/members/{rank}/logs streams a member's container output as server-sent events (output, notice when there is none to give, then end); follow=true keeps it open. Output comes from the member's host and is gone once its container is removed. curl: ```bash # A member's container output as server-sent events, from its host (?follow=true keeps it open). LINE="" for _ in 1 2 3 4 5 6 7 8 9 10; do LINE=$(curl -sS --fail-with-body "$API_BASE_URL/clusters/$CLUSTER_ID/members/1/logs?tail=20" \ -H "$AUTH" | sed -n 's/^data: //p' | jq -r 'select(.text) | .text' | sed -n 1p) [ -n "$LINE" ] && break sleep 2 done echo "member 1 says: $LINE" ``` TypeScript: ```typescript // A member's container output, from its host (`follow: true` keeps the stream open). let line = ''; for (let attempt = 0; attempt < 10 && !line; attempt++) { if (attempt) await new Promise((r) => setTimeout(r, 2000)); for await (const event of await client.clusters.streamMemberLogs(cluster.id, 1, { tail: 20, })) { if (event.event === 'output') line = (event.data as { text: string }).text.trim(); if (event.event === 'end') break; } } console.log('member 1 says:', line); ``` Python: ```python # A member's container output, from its host (follow=True keeps the stream open). line = "" for attempt in range(10): if attempt: time.sleep(2) with client.clusters.stream_member_logs(cluster["id"], 1, tail=20) as events: for event in events: if event.event == "output": line = event.data["text"].strip() if event.event == "end": break if line: break print("member 1 says:", line) ``` CLI: ```bash LINE="" for _ in 1 2 3 4 5 6 7 8 9 10; do LINE=$(hayonix clusters logs "$CLUSTER_ID" --rank 1 --tail 20 | sed -n 1p) [ -n "$LINE" ] && break sleep 2 done echo "member 1 says: $LINE" ``` ## Delete it Deleting is irreversible: every member is stopped and removed, billing ends with each member's container, the shared volume's data is destroyed and the network is freed. curl: ```bash # Irreversible: every member, the network and the shared volume's data are destroyed. delete_cluster() { curl -sS --fail-with-body -X DELETE "$API_BASE_URL/clusters/$CLUSTER_ID" -H "$AUTH" >/dev/null echo "deleted $CLUSTER_ID" } trap delete_cluster EXIT ``` TypeScript: ```typescript // Irreversible: every member, the network and the shared volume's data are destroyed. await client.clusters.delete(cluster.id); console.log('deleted', cluster.id); ``` Python: ```python # Irreversible: every member, the network and the shared volume's data are destroyed. client.clusters.delete(cluster["id"]) print("deleted", cluster["id"]) ``` CLI: ```bash delete_cluster() { hayonix clusters delete "$CLUSTER_ID" --yes echo "deleted $CLUSTER_ID" } trap delete_cluster EXIT ``` ## Known limits - No resize, no reconfigure. Members, hardware, image and network are fixed when the cluster is created; create a new cluster for a new shape. - No stop and start. A cluster runs until it is deleted (or stopped by the platform, after which only deletion remains). - Members are never moved or restarted, on failure, on host loss or on host maintenance. - GPU members and high-speed fabrics are unverified. Clusters have run on CPU members only (torchrun with gloo); GPU members and NCCL across hosts have not been exercised, nor has mpirun. Traffic between hosts goes over the encrypted network, not InfiniBand or RoCE. --- # Cache models on hosts URL: https://hayonix.ai/docs/quickstarts/model-cache Pin a model from the model hub to a commit, mount it into serverless workers and pods from the host’s model cache, and load it with networking off, so a worker on a host that already holds the model starts without downloading it. Most of a model worker's cold start is often the model download, not the container. Instead of baking weights into your image or downloading them in your handler, name the model in the workload: the host fetches it once into its model cache, checks every file's size and digest, and mounts it read-only into each container that asks for it. A later worker on a host that already holds the model starts without downloading anything. You name a model through a model reference: a repository on the model hub, pinned to one commit. Serverless releases and pods list references in models. ## Accept a model reference Give the model as owner/name or owner/name@revision, where the revision is a branch, a tag or a commit (default main). The API checks the reference against the model hub before it answers (a few seconds): the repository exists, the revision resolves, and the files are listed with their sizes and digests. A branch is pinned to the commit it points at now, so a later push to the branch never changes what your workers run; accept a new reference to move to a newer commit. Nothing is downloaded yet. include keeps only the files that match one of its patterns (* matches any characters, / included; ? one character), so a repository that holds several formats or quantisations is fetched only in the one you use. curl: ```bash REF=$( jq -n --arg model "$MODEL_REF" '{model: $model, include: ["*.json", "*.txt"]}' | curl -sS --fail-with-body "$API_BASE_URL/model-references" \ -H "$AUTH" -H "Content-Type: application/json" -d @- ) REF_ID=$(echo "$REF" | jq -r .id) echo "$REF" | jq -r '"reference \(.id) \(.repository) at \(.commit[0:7])", "files: \(.file_count) bytes: \(.total_bytes) visibility: \(.visibility)"' ``` TypeScript: ```typescript import { Client, ConflictError } from 'hayonix'; const client = new Client(); const ref = await client.modelReferences.create({ model: process.env.MODEL_REF ?? 'hf-internal-testing/tiny-random-gpt2@main', include: ['*.json', '*.txt'], // only these files; default: every file of the revision }); console.log('reference', ref.id, ref.repository, 'at', ref.commit.slice(0, 7)); console.log('files:', ref.file_count, 'bytes:', ref.total_bytes, 'visibility:', ref.visibility); ``` Python: ```python import os import time from hayonix import Client, ConflictError client = Client() ref = client.model_references.create( model=os.environ.get("MODEL_REF", "hf-internal-testing/tiny-random-gpt2@main"), include=["*.json", "*.txt"], # only these files; default: every file of the revision ) print("reference", ref["id"], ref["repository"], "at", ref["commit"][:7]) print("files:", ref["file_count"], "bytes:", ref["total_bytes"], "visibility:", ref["visibility"]) ``` CLI: ```bash REF=$(hayonix api modelReferences.create \ --body "$(jq -n --arg model "$MODEL_REF" '{model: $model, include: ["*.json", "*.txt"]}')" --json) REF_ID=$(echo "$REF" | jq -r .id) echo "$REF" | jq -r '"reference \(.id) \(.repository) at \(.commit[0:7])", "files: \(.file_count) bytes: \(.total_bytes) visibility: \(.visibility)"' ``` The reference records what it resolved to: commit (40 hex characters), files with each one's size and digest, file_count, total_bytes, and snapshot_path, the directory that holds the files inside a container. | Error code | Meaning | | invalid_model | model is not owner/name or owner/name@revision | | model_not_found | no such repository, or it is private and no token was given | | revision_not_found | the repository has no such branch, tag or commit | | model_access_denied | the repository is gated or private and the token cannot read it | | no_matching_files | no file of the revision matches include | | unsupported_file_name | a file name cannot be cached (letters, digits, ., _ and - only); leave it out with include | | model_too_large | the selected files exceed the size a reference may have; narrow it with include | | unknown_secret | token_secret_id is not a secret of this project | | model_hub_unavailable | the model hub did not answer in time: retry | ## Private and gated models For a private or gated repository, store an access token for the model hub as a project secret and pass its ID as token_secret_id. The reference is then visibility: private: hosts download it with that token and keep its files for this project only, so another project on the same host never mounts them, even for the same commit. Your containers never see the token. Public models are shared across projects on a host: the second project to mount one starts as fast as the first project's second worker. ## Mount it in a serverless endpoint List the reference in the release's models (up to 8, one revision per repository). Before a worker's container starts, its host makes each model present, downloading only what it does not hold yet, then mounts it read-only. Changing models makes a new release, rolled out like any other. curl: ```bash ENDPOINT_ID=$( echo "$REF" | jq --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "model-reader", image: $image, skus: [$sku], region: $region, max_workers: 1, models: [{reference_id: .id}], env: [{name: "MODEL_REPOSITORY", value: .repository}, {name: "MODEL_COMMIT", value: .commit}] }' | curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints" \ -H "$AUTH" -H "Content-Type: application/json" -d @- | jq -r .id ) echo "endpoint $ENDPOINT_ID mounts $(echo "$REF" | jq -r .snapshot_path)" ``` TypeScript: ```typescript const image = process.env.IMAGE ?? 'registry.example.com/team/model-reader:1.0.0'; const sku = process.env.SKU ?? 'cpu-2c-4gb'; const region = process.env.REGION ?? 'dev-local-1'; const endpoint = await client.serverless.createEndpoint({ name: 'model-reader', image, skus: [sku], region, max_workers: 1, models: [{ reference_id: ref.id }], env: [ { name: 'MODEL_REPOSITORY', value: ref.repository }, { name: 'MODEL_COMMIT', value: ref.commit }, ], }); console.log('endpoint', endpoint.id, 'mounts', ref.snapshot_path); ``` Python: ```python image = os.environ.get("IMAGE", "registry.example.com/team/model-reader:1.0.0") sku = os.environ.get("SKU", "cpu-2c-4gb") region = os.environ.get("REGION", "dev-local-1") endpoint = client.serverless.create_endpoint( name="model-reader", image=image, skus=[sku], region=region, max_workers=1, models=[{"reference_id": ref["id"]}], env=[ {"name": "MODEL_REPOSITORY", "value": ref["repository"]}, {"name": "MODEL_COMMIT", "value": ref["commit"]}, ], ) print("endpoint", endpoint["id"], "mounts", ref["snapshot_path"]) ``` CLI: ```bash BODY=$(echo "$REF" | jq --arg image "$IMAGE" --arg sku "$SKU" --arg region "$REGION" '{ name: "model-reader", image: $image, skus: [$sku], region: $region, max_workers: 1, models: [{reference_id: .id}], env: [{name: "MODEL_REPOSITORY", value: .repository}, {name: "MODEL_COMMIT", value: .commit}] }') ENDPOINT_ID=$(hayonix api serverless.createEndpoint --body "$BODY" -q) echo "endpoint $ENDPOINT_ID" ``` This worker reads the repository and commit from environment variables set from the reference; a worker that always serves one model may hard-code them instead. ## Load it with networking off Inside the container each model appears at /model-cache/models----, laid out the way the model hub's client libraries keep their cache (the files of the commit under snapshots//). HF_HUB_CACHE is set to /model-cache unless your environment sets HF_HUB_CACHE or HF_HOME itself, so the client libraries find the model without being told where it is. Set HF_HUB_OFFLINE=1 and ask for the reference's commit with local_files_only=True: the call resolves to the mounted directory, and fails at once rather than downloading if the model is missing. Loading with from_pretrained works the same way with HF_HUB_OFFLINE=1 set. handler.py: ```python import json import os # The model is already on the host and mounted read-only: never reach for the network. os.environ.setdefault("HF_HUB_OFFLINE", "1") import serverless_worker as sw # noqa: E402 from huggingface_hub import snapshot_download # noqa: E402 # Set on the endpoint from the model reference (its repository and the commit it is pinned to). REPOSITORY = os.environ["MODEL_REPOSITORY"] COMMIT = os.environ["MODEL_COMMIT"] # Once per worker, at start: HF_HUB_CACHE points at the mounted cache, so this only resolves a # path. With local_files_only it fails loudly instead of downloading if the model is missing. path = snapshot_download(REPOSITORY, revision=COMMIT, local_files_only=True) with open(os.path.join(path, "config.json")) as f: config = json.load(f) def handler(job: sw.Job): """Answers from the loaded model: here, what its configuration says.""" return { "repository": REPOSITORY, "commit": COMMIT, "model_type": config.get("model_type"), "files": sorted(os.listdir(path)), } if __name__ == "__main__": sw.serve(handler) ``` The image needs the model hub client, not the model: Dockerfile: ```text # The worker base image plus the model hub client. The model itself is not in the image: hosts # cache it and mount it into the container before the worker starts. ARG BASE=registry.example.com/team/serverless-worker:0.1.0 FROM ${BASE} USER root RUN pip install --no-cache-dir huggingface_hub==2.4.0 USER 10001 COPY handler.py /app/handler.py CMD ["python", "/app/handler.py"] ``` Build and push: ```bash IMAGE=registry.example.com/team/model-reader:1.0.0 docker build -t "$IMAGE" . docker push "$IMAGE" ``` The mount is read-only: Write anything derived from the model (compiled kernels, converted weights) to the container disk or a volume, not under /model-cache. ## Run a job The first job on a new endpoint waits for a worker to start, which now includes the host fetching the model unless it already holds it. curl: ```bash JOB_ID=$( curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID/jobs" \ -H "$AUTH" -H "Content-Type: application/json" -d '{"input": {}}' | jq -r .id ) # Long-poll until the job finishes (the first job waits for a worker to start). for _ in $(seq 15); do JOB=$(curl -sS --fail-with-body "$API_BASE_URL/serverless/jobs/$JOB_ID?wait=60" -H "$AUTH") case "$(echo "$JOB" | jq -r .state)" in queued | running) ;; *) break ;; esac done echo "$JOB" | jq -r '"state: \(.state) model_type: \(.output.model_type)"' ``` TypeScript: ```typescript const job = await client.serverless.submitJob(endpoint.id, { input: {} }); const done = await client.waitFor.job(job.id, { timeout: 900_000 }); const output = (done.output ?? {}) as { model_type?: string }; console.log('state:', done.state, 'model_type:', output.model_type); ``` Python: ```python job = client.serverless.submit_job(endpoint["id"], input={}) done = client.wait_for.job(job["id"], timeout=900) output = done.get("output") or {} print("state:", done["state"], "model_type:", output.get("model_type")) ``` CLI: ```bash hayonix serverless run "$ENDPOINT_ID" --input '{}' --wait-timeout 15m --json | jq -r '"state: \(.state) model_type: \(.output.model_type)"' ``` ## See how a worker started Each worker lists the steps of its start in start, in order: the image, each model, the container. The console's Workers tab shows the same steps, live while a worker starts. Loading inside the container ends when the worker is ready (ready_at). curl: ```bash curl -sS --fail-with-body "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID/workers" -H "$AUTH" | jq -r '.data[].start[] | if .step == "model" then "model \(.repository) \(.state) downloaded bytes: \(.bytes_downloaded // 0)" else "\(.step) \(.state)" end' ``` TypeScript: ```typescript const workers = await client.serverless.listWorkers(endpoint.id); for (const worker of workers.data) { for (const step of worker.start) { if (step.step === 'model') // cached (nothing downloaded) or downloaded console.log( 'model', step.repository, step.state, 'downloaded bytes:', step.bytes_downloaded ?? 0, ); else console.log(step.step, step.state); } } ``` Python: ```python for worker in client.serverless.list_workers(endpoint["id"]): for step in worker["start"]: if step["step"] == "model": print( "model", step["repository"], step["state"], # cached (nothing downloaded) or downloaded "downloaded bytes:", step.get("bytes_downloaded", 0), ) else: print(step["step"], step["state"]) ``` CLI: ```bash hayonix api serverless.listWorkers "$ENDPOINT_ID" --json | jq -r '.data[].start[] | if .step == "model" then "model \(.repository) \(.state) downloaded bytes: \(.bytes_downloaded // 0)" else "\(.step) \(.state)" end' ``` | Step | States | | image | pulling, pulled, present (already on the host), failed | | model | cached (found in the host's model cache: nothing downloaded), downloading (with bytes_done of bytes_total), downloaded (with bytes_downloaded and seconds), failed | | container | started | bytes_downloaded counts what this fetch received from the network: 0 when everything was cached, less than bytes_total when part of the model was already there or an interrupted download was resumed. ## Pods Pods take models too, on create and on reconfigure, and see the same mount and HF_HUB_CACHE. Changing a pod's models recreates its container: only volumes survive. ## Delete it A reference can be deleted once nothing mounts it: no live workload, and no endpoint whose current release names it (409 with code model_reference_in_use until then). Hosts drop its files as their caches fill. curl: ```bash delete_all() { curl -sS --fail-with-body -X DELETE "$API_BASE_URL/serverless/endpoints/$ENDPOINT_ID" \ -H "$AUTH" >/dev/null # A reference can be deleted once nothing mounts it (409 until the worker has stopped). for _ in $(seq 60); do CODE=$(curl -sS -o /dev/null -w '%{http_code}' -X DELETE \ "$API_BASE_URL/model-references/$REF_ID" -H "$AUTH") [ "$CODE" = 200 ] && break [ "$CODE" = 409 ] || { echo "deleting $REF_ID: HTTP $CODE"; return 1; } sleep 2 done echo "deleted $ENDPOINT_ID and $REF_ID" } trap delete_all EXIT ``` TypeScript: ```typescript await client.serverless.deleteEndpoint(endpoint.id); // A reference can be deleted once nothing mounts it: wait for the worker to stop. const deleteReference = async (tries: number): Promise => { try { await client.modelReferences.delete(ref.id); } catch (err) { if (!(err instanceof ConflictError) || tries <= 1) throw err; await new Promise((r) => setTimeout(r, 2000)); await deleteReference(tries - 1); } }; await deleteReference(60); console.log('deleted', endpoint.id, 'and', ref.id); ``` Python: ```python client.serverless.delete_endpoint(endpoint["id"]) # A reference can be deleted once nothing mounts it: wait for the worker to stop. for _ in range(60): try: client.model_references.delete(ref["id"]) break except ConflictError: time.sleep(2) else: raise RuntimeError(f"{ref['id']} is still in use") print("deleted", endpoint["id"], "and", ref["id"]) ``` CLI: ```bash delete_all() { hayonix serverless delete "$ENDPOINT_ID" -y # A reference can be deleted once nothing mounts it: retry while the worker stops. for _ in $(seq 60); do hayonix api modelReferences.delete "$REF_ID" -q >/dev/null 2>&1 && break sleep 2 done hayonix api modelReferences.get "$REF_ID" -q >/dev/null 2>&1 && { echo "$REF_ID still in use"; return 1; } echo "deleted $ENDPOINT_ID and $REF_ID" } trap delete_all EXIT ``` ## How the cache behaves - Each host's cache has a budget. When a new model needs the room, the models no running or paused workload mounts are evicted, least recently used first; a mounted file is never removed. If that frees too little, the fetch fails with model_cache_full and is retried later. - New work is placed, where the hardware allows, on a host that already holds its models. - Files are content-addressed and verified: a file that does not match its recorded size and digest is never mounted. - A host may be warmed ahead of a launch by the platform; that changes how fast a worker starts, never what it runs. ## Next - Your first serverless endpoint: the worker runtime and the job lifecycle. - Serve HTTP from a serverless endpoint: the same models work for HTTP endpoints, and fast resume keeps a loaded model warm. --- # Projects and API keys URL: https://hayonix.ai/docs/concepts/projects-and-keys How organizations, projects and keys relate, what a key may be allowed to do, and when a request needs X-Project-Id. ## Organizations and projects An organization holds the members, the credit balance, billing settings and quotas. It contains one or more projects, and every resource you create (pods, volumes, secrets, endpoints, files, fine-tunes, batches) lives in exactly one project. IDs have a type prefix (pod_, vol_, sep_…) and are unique across the platform; an ID from another project is answered with 404, the same as an ID that never existed. Routes come in two shapes: - Project-level routes are short: /v1/pods, /v1/files/{file_id}. They act in the project of the caller. - Organization-level routes carry the org in the path: /v1/orgs/{org_id}/billing/balance. The SDKs fill in your key's org when you leave org_id out; GET /v1/caller returns it. ## API keys A key belongs to one project and acts only in it: requests made with a key never name a project. Send it as a bearer token: ```http Authorization: Bearer sk_… ``` A key carries scopes: actions written resource:verb (file:create, inference:invoke) or resource:* for every verb on a resource. A key can hold at most what the member who created it may do, and only actions on the project's own resources plus a few organization reads: | Scope | Allows | | inference:invoke | Calling models through the inference API | | model:read | Listing and reading models | | workload:* | Pods | | volume:*, template:* | Volumes and pod templates | | serverless_endpoint:*, serverless_job:* | Serverless endpoints and their jobs | | model_reference:* | Model references (models cached on hosts and mounted into workloads) | | webhook:* | Webhook destinations and delivery logs (webhook:read reads serverless completion deliveries too); receiving organization events also needs billing:read | | dedicated_endpoint:* | Dedicated endpoints | | file:*, fine_tune_job:*, batch:*, evaluation:* | Files, fine-tuning, batches and evaluations | | sandbox:* | Code sandboxes: create, run code, move files, extend and end | | cluster:* | Clusters: create, read, rename and delete | | secret:*, ssh_key:*, registry_credential:* | Project secrets, SSH keys and registry credentials | | billing:read, usage:read, project:read | The balance, usage and cost reports, the project | A key can never hold api_key scopes, so a leaked key cannot create more keys or keep itself alive: create, rotate and revoke keys in the console. Member, invitation and organization settings, top-ups and payment methods are also console-only. A key may have an expiry date; an expired or revoked key gets 401. Requests with a key that lacks a scope get 403 with type permission_error. Keep keys secret: The secret is shown once, when the key is created; the platform keeps only a keyed hash of it and cannot show it again. Put it in a secret manager or an environment variable, never in source code or in a browser. ## Console sessions and X-Project-Id The console calls the same API with a signed-in session instead of a key. A session is not tied to a project, so project-level requests made with a session must send the project explicitly: ```http X-Project-Id: prj_… ``` The server never remembers an "active" project between requests. With an API key the header is not needed: the key already names its project. A few operations accept only a session; the API reference marks them Console session. --- # Billing and credit URL: https://hayonix.ai/docs/concepts/billing Prepaid credit, how amounts are written (integer nano-USD), how holds reserve credit for work in flight, and what happens when credit runs out. ## Prepaid credit You pay before you use: top up the organization's balance in the console, and every charge is taken from it. There are two kinds of credit: paid credit from top-ups, and promotional credit granted to the organization, which can expire. Promotional credit is spent along with paid credit. GET /v1/orgs/{org_id}/billing/balance returns: | Field | Meaning | | paid | Paid credit. Negative when the organization is overdrawn. | | promo | Spendable promotional credit. | | held | Credit reserved by work in flight (see holds below). | | available | paid + promo: what new work may use. | Usage is recorded as individual usage events and rated against the price book, so every charge on the balance traces back to the usage that caused it. The cost report (GET /v1/orgs/{org_id}/usage/costs) breaks spend down by product, project and model. ## Amounts are nano-USD strings Every amount in the API is an integer number of nano-USD (one billionth of a dollar: $1 = 1000000000) sent as a decimal string, for example "1500000000" for $1.50. Per-token prices are far below a cent, so cents would round them away, and floating point would drift. Keep amounts as strings or big integers; never parse them into a float. The SDKs format and parse them exactly: TypeScript: ```typescript import { formatCost, formatUsd, parseUsd } from 'hayonix'; const balance = await client.billing.getBalance(); // the key's org is filled in for you console.log('available:', formatUsd(balance.available)); // e.g. "$25.00" console.log('exact:', formatUsd(balance.available, { maxDecimals: 9 })); console.log('a tiny charge:', formatCost('184331')); // "<$0.01" console.log('$5 in nano-USD:', parseUsd('5')); // "5000000000" ``` ## Holds Work whose final cost is not known yet reserves credit first. An inference request holds its worst-case cost while it runs and settles at its real token count; a fine-tuning job holds its estimated cost when it is created. If the hold cannot be made, the request is refused with 402 and type insufficient_credit_error before anything runs. ## When credit runs out An organization is out of credit when available is zero or less. Then: - new launches, inference requests, jobs and batches are refused with 402; - running compute (pods, serverless workers, dedicated endpoints) keeps running for a grace period of 60 minutes so you can top up without losing work, then it is stopped. Volumes are kept, and a warning goes out shortly before the stop. Spending fast enough to overdraw the balance by a large amount stops compute sooner; - when credit is back above zero, new work can start again at once. Compute that was stopped stays stopped until you start it. You can also set spend limits on the organization: one for the trailing hour and one for the calendar month. An alert goes out at 80 % of a limit. Reaching one refuses new billable work with 402 and code spend_limit_reached and stops running compute the same way as running out of credit; the limit clears by itself when the window moves on or when you raise it. Auto-recharge tops up from a saved card when the balance falls below a threshold, at most once every 10 minutes and up to a monthly cap. Credit is only granted by payments: A top-up becomes credit when the payment processor confirms the payment, never when a checkout page redirects back. That can take a few seconds after you pay. --- # How compute is billed URL: https://hayonix.ai/docs/concepts/compute-billing Per-second billing from the node agent’s own record of what ran, what a pod costs running and stopped, and how storage is metered. ## Per second, from evidence Pods, serverless workers and dedicated endpoint replicas are billed per second. The seconds come from the agent on the machine that ran the container: it keeps a journal of when each container started and stopped and reports it to the platform. Only whole seconds the journal proves are billed. Time the platform cannot prove (a machine that stopped reporting, for example) is not billed. Prices are set per second and shown per hour. A price of $0.054 per hour is $0.000015 per second, which is exactly 15,000 nano-USD. ## Running, stopped and terminated pods | State | Compute | Container disk | Pod volume | Network volumes | | Running | billed | billed | billed | billed | | Stopped | not billed | not billed | billed | billed | | Terminated | not billed | gone | deleted unless kept | billed until deleted | GET /v1/pods/estimate returns a configuration's price while running and while stopped, line by line, from the price book in force. ## Storage Storage is metered in GB-seconds: a volume's size times the seconds it exists. A network volume is billed from creation until you delete it, whether or not a pod uses it. ## Serverless workers and dedicated endpoints A serverless worker is billed per second while its container runs, including the time it waits for jobs before its idle timeout removes it; an endpoint with no workers costs nothing. A dedicated endpoint replica is billed per second from the moment it is ready to serve, not while it loads; requests to a dedicated endpoint are not charged per token. ## Interruptible pods A pod created with pricing_class: interruptible costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue and runs again when there is room. On-demand pods are never preempted. --- # Storage and volumes URL: https://hayonix.ai/docs/concepts/storage Container disk, pod volumes and network volumes: what each is for, what survives a stop or a configuration change, and where volumes live. ## Three kinds of storage | Kind | Lives | Survives | | Container disk (container_disk_gb) | Inside the container | Nothing: it is reset whenever the container is recreated | | Pod volume (volume) | Mounted in one pod | Stops, restarts, resets and configuration changes; deleted when the pod is terminated, unless you keep it | | Network volume (/v1/volumes) | On its own, mounted into pods | Everything until you delete it | A new volume's top directory is writable by every user (mode 1777, like /tmp), so an image that runs as an unprivileged user can use it at once. It is set only when the volume is created: if you change its owner or mode, that stays. If the mount path already exists in the image with files in it, the container engine copies those files, their owner and the directory's mode into an empty volume the first time it is mounted there. ## A configuration change recreates the container Changing a pod's configuration (image, environment, command, ports, hardware, mounted volumes) replaces its container. Only volume data survives: anything written to the container disk is gone, and running processes are restarted. Stopping and starting a pod also gives it a fresh container. Keep data you need on a volume. ## Restart or reset | Action | Container disk | Volumes | Host and GPUs | Identity, addresses, settings | | POST /v1/pods/{pod_id}/restart | kept | kept | kept | kept | | POST /v1/pods/{pod_id}/reset | fresh (recreated from the image) | kept | kept | kept | A reset is for a pod whose container disk you want back to the image's state (a broken install, a full disk) without giving up its host, GPUs or volumes. It works on a pod that is on a host (running, or whose main process exited); a stopped pod already starts with a fresh container disk. Billing continues as for a running pod: the old container's time ends when it stops, the new one's starts when it starts. The CLI's pods reset asks before it resets. Adding or removing an SSH key is the exception: keys reach the machine separately and never recreate a container. ## Volumes live on one host Until shared storage is available, a volume is stored on the machine of the first pod that mounts it, and is then pinned to that host: every pod that mounts it, now or later, runs there, and waits for capacity on that host when it is full. pinned_to_host on a volume shows this. ## Network volumes on serverless workers A serverless endpoint (queue or HTTP) can mount network volumes of its project into every worker: set volumes on the endpoint, each with a mount_path and read_only (default false). Mounts belong to the release, so changing them rolls out a new release like any other change to the worker. Workers and pods that mount the same volume see the same files, which is how a pod can prepare data that jobs then read. The same rule applies as for pods: a volume lives on one host, so every worker of the endpoint runs on that host and waits for capacity there when it is full, even when other hosts have room. Choose hardware that host has. A worker's claim on a volume ends when the worker ends; a paused worker (fast resume) keeps it. A volume an endpoint uses cannot be deleted: DELETE /v1/volumes/{volume_id} answers 409 volume_attached while the endpoint's current release mounts it or a worker of an older release still runs. endpoint_attachments on the volume lists those endpoints. ## Growing and deleting ## Sizes are enforced A volume holds no more than its size, and a container disk no more than container_disk_gb (sizes are in GiB): a write beyond it fails with a disk-quota error, as on a full disk. The space used is measured on the host while a pod or worker mounts the volume: usage on the volume, used_bytes on each of a pod's volumes and container_disk on the pod, also shown on the pod's Metrics tab and on the Volumes page. ## Growing and deleting Volumes can grow but never shrink. Growing one moves its limit on the host at once, without restarting the containers that use it. Deleting a volume deletes its data at once and stops its billing; a volume that is mounted must be detached first. --- # Limits and quotas URL: https://hayonix.ai/docs/concepts/limits Organization quotas on resources, inference rate limits per model, the rate-limit headers every response carries, and what to do when you hit one. ## Quotas Each organization has quotas on how much it can run at once: GPUs, pods, serverless workers and endpoints, dedicated endpoints and their replicas, volume gigabytes, fine-tuning jobs and open batches. A new organization starts with small limits, which rise once it has made a payment that has aged for 7 days. You can ask for higher limits. Going over a quota is refused with 429, type quota_exceeded_error and code quota_exceeded; param names the quota (for example pods). Unlike a rate limit, retrying does not help: free something up first (terminate a pod, delete an endpoint) or ask for a higher limit. The SDKs never retry a quota error. ## Rate limits The API limits requests per key. The inference API also limits requests and tokens per minute, per organization and model; batches have a separate allowance so a large batch does not slow interactive traffic. Every response carries the state of the limit it was counted against: | Header | Meaning | | x-ratelimit-limit-requests | Requests allowed in the window | | x-ratelimit-remaining-requests | Requests left in the window | | x-ratelimit-reset-requests | Time until the window resets, such as 12s | | x-ratelimit-limit-tokens, x-ratelimit-remaining-tokens, x-ratelimit-reset-tokens | The same for tokens (inference) | | ratelimit-limit, ratelimit-remaining, ratelimit-reset | Request limit, remaining and reset in seconds | | retry-after | Seconds to wait, on a refused request | A request over the limit gets 429 with type rate_limit_error. Wait for retry-after and send it again; the SDKs do this for you. ## Rate-limit levels The per-minute inference and batch limits depend on your organization's level. Every organization starts on the first level; higher levels raise every limit. A level is reached by two facts together: credit paid and kept (card payments, less refunds and open disputes; promotional credit does not count) and account age. Your level rises by itself, within minutes of a payment or of the account reaching the age, and never goes down by itself. If you need more than your level gives, ask us: a limit set for your organization wins over its level. GET /v1/orgs/{org_id}/billing/rate-level returns your level, the limits in force and what the next level needs; the console shows the same on the Billing page. CLI: ```bash hayonix billing rate-limits # your level, its per-minute limits and what reaches the next one ``` --- # Errors and retries URL: https://hayonix.ai/docs/concepts/errors The one error envelope, its types and codes, the SDK error classes, and which failures are retried automatically. ## The error envelope Every error, from the control-plane API and from the inference API alike, has one shape: ```json { "error": { "message": "quota exceeded for pods (limit 3)", "type": "quota_exceeded_error", "code": "quota_exceeded", "param": "pods" } } ``` type is the broad class and decides how to react; code is the precise reason, stable enough to branch on; param names the request field or header the error is about, when there is one; message is for people and may change. Every response carries X-Request-Id: quote it when you report a problem. | Status | type | Typical code | Meaning | | 400 | invalid_request_error | invalid_value | The request is malformed or a value is not allowed | | 401 | authentication_error | invalid_api_key | Missing, malformed, revoked or expired key | | 402 | insufficient_credit_error | insufficient_credit, spend_limit_reached | Out of credit, or a spend limit is reached | | 403 | permission_error | forbidden, organization_suspended | The key's scopes or the organization's standing do not allow it | | 404 | not_found_error | not_found, route_not_found | No such resource in this project, or no such route | | 409 | conflict_error | already_exists | The resource's current state does not allow this | | 409 | conflict_error | idempotency_in_progress | A request with this Idempotency-Key is still running | | 422 | idempotency_error | idempotency_key_reused | The key was used with a different request | | 429 | quota_exceeded_error | quota_exceeded | An organization quota is reached | | 429 | rate_limit_error | rate_limited | Too many requests; see retry-after | | 5xx | api_error | internal_error | Something failed on our side | ## SDK error classes Both SDKs raise one class per type, all subclasses of ApiError, which carries status, type, code, param and the request ID: | Class | For | | InvalidRequestError | 400 (and 422 other than idempotency) | | AuthenticationError | 401 | | InsufficientCreditError | 402 | | PermissionDeniedError | 403 | | NotFoundError | 404 | | ConflictError | 409 | | IdempotencyError | any Idempotency-Key problem | | QuotaExceededError | 429 quota | | RateLimitError | 429 rate limit | | ServerError | 5xx | Failures before any answer arrives are NetworkError and RequestTimeoutError. The waiting helpers add WaitTimeoutError (time ran out) and UnexpectedStateError (the resource reached a state it cannot leave for the one you waited for). TypeScript: ```typescript import { ApiError, NotFoundError, RateLimitError } from 'hayonix'; try { await client.pods.get('pod_00000000000000000000000000'); } catch (err) { if (err instanceof NotFoundError) { console.log('not found:', err.message); } else if (err instanceof RateLimitError) { console.log('slow down; retry after', err.retryAfterSeconds, 's'); } else if (err instanceof ApiError) { console.log(err.status, err.type, err.code, err.param, 'request', err.requestId); } else { throw err; } } ``` Python: ```python from hayonix import ApiError, NotFoundError, RateLimitError try: client.pods.get("pod_00000000000000000000000000") except NotFoundError as err: print("not found:", err.message) except RateLimitError as err: print("slow down; retry after", err.retry_after_seconds, "s") except ApiError as err: print(err.status, err.type, err.code, err.param, "request", err.request_id) ``` ## What is retried The SDKs and the CLI retry a failure only when doing the request twice cannot do anything twice: - Safe requests (GET, PUT, DELETE) and creating requests, which always carry an Idempotency-Key, are retried after a network failure, a timeout, 408, 409 idempotency_in_progress and 5xx. - Every request is retried after a 429 rate limit, because the limiter answers before anything runs. The wait is retry-after when the server sends it. - Other POST and PATCH requests are never retried once they may have reached the server, and a quota error is never retried. Retries back off exponentially with jitter (about 0.5 s, 1 s, 2 s, capped at 8 s). By default a call is retried twice; a server-requested wait longer than 60 seconds is not attempted. Both are client options. If you write your own client, follow the same rules, and send an Idempotency-Key on every creating request so that a retry is always safe. --- # Idempotency URL: https://hayonix.ai/docs/concepts/idempotency Make creating requests safe to retry with the Idempotency-Key header: what is stored, for how long, and the two ways a key is refused. A network failure can leave you not knowing whether a request reached the server. For reads that does not matter; for a request that creates a pod or submits a job, sending it again could create a second one. Idempotency-Key removes the doubt. ## How it works Every creating POST accepts an Idempotency-Key header: any string of 1 to 255 characters, unique per operation you intend, such as a UUID. - The first request with a key runs, and its response is stored with the key for 24 hours. - A repeat with the same key and the same request gets the stored response, with the original status, and the header Idempotent-Replayed: true. Nothing runs a second time. - If the first request failed, nothing is stored and the key can be used again. Keys are scoped to the credential that sent them, so they never collide with another customer's or another key's. curl: ```bash KEY=$(cat /proc/sys/kernel/random/uuid) # any unique string up to 255 characters BODY=$(jq -n --arg name "$NAME" '{name: $name, value: "example-value"}') for attempt in 1 2; do curl -sS --fail-with-body -D "headers.$attempt" "$API_BASE_URL/secrets" \ -H "$AUTH" -H "Content-Type: application/json" \ -H "Idempotency-Key: $KEY" -d "$BODY" | jq -r '"attempt '"$attempt"': \(.id)"' grep -i '^idempotent-replayed' "headers.$attempt" || echo "(first answer)" done ``` TypeScript: ```typescript import { randomUUID } from 'node:crypto'; import { Client, IdempotencyError } from 'hayonix'; const client = new Client(); const key = randomUUID(); // store it with the work item, so a restarted job reuses it const first = await client.secrets.create( { name, value: 'example-value' }, { idempotencyKey: key }, ); const again = await client.secrets.create( { name, value: 'example-value' }, { idempotencyKey: key }, ); console.log('same secret:', first.id === again.id); ``` Python: ```python import uuid from hayonix import Client, IdempotencyError client = Client() key = str(uuid.uuid4()) # store it with the work item, so a restarted job reuses it first = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key}) again = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key}) print("same secret:", first["id"] == again["id"]) ``` ## When a key is refused - The same key with a different request (another body, path or project) is refused with 422, type idempotency_error and code idempotency_key_reused. - A repeat that arrives while the first is still running gets 409 with code idempotency_in_progress. Wait and retry; it will then get the stored response. TypeScript: ```typescript try { await client.secrets.create({ name, value: 'a different value' }, { idempotencyKey: key }); throw new Error('expected the reused key to be refused'); } catch (err) { if (err instanceof IdempotencyError) console.log('refused:', err.code); // idempotency_key_reused else throw err; } ``` Python: ```python try: client.secrets.create(name=name, value="a different value", request_options={"idempotency_key": key}) except IdempotencyError as err: print("refused:", err.code) # idempotency_key_reused else: raise SystemExit("expected the reused key to be refused") ``` ## In the SDKs The SDKs send a fresh key with every creating call and keep it across their own retries. Pass your own key (idempotencyKey in TypeScript, request_options={"idempotency_key": …} in Python) when the retry may come from another process, such as a job runner that restarts: store the key with the work item before you send the request. For uploads (POST /v1/files) the stored identity is the file content: a retry with the same key, purpose, file name and bytes returns the original file. --- # Pagination URL: https://hayonix.ai/docs/concepts/pagination Every list is cursor-paginated: read data and follow next_cursor until it is null, or let the SDKs iterate for you. ## Pages and cursors Every list operation returns one page: ```json { "data": [ … ], "next_cursor": "c2VjXzAx…" } ``` Pass next_cursor back as cursor to get the following page; the last page has "next_cursor": null. limit sets the page size (1 to 200, default 50 on most lists). Cursors are opaque: do not build or parse them. Stop when next_cursor is null, not when a page looks short. curl: ```bash # Follow `next_cursor` until it is null. CURSOR="" PAGE_NO=1 while :; do PAGE=$(curl -sS --fail-with-body -G "$API_BASE_URL/secrets" -H "$AUTH" \ --data-urlencode "limit=2" ${CURSOR:+--data-urlencode "cursor=$CURSOR"}) echo "page $PAGE_NO: $(echo "$PAGE" | jq -r '[.data[].name] | join(", ")')" CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty') [ -z "$CURSOR" ] && break PAGE_NO=$((PAGE_NO + 1)) done ``` TypeScript: ```typescript // One page at a time: `data` and `nextCursor`, or `nextPage()` until it returns null. let page = await client.secrets.list({ limit: 2 }); for (let n = 1; ; n++) { console.log( `page ${n}: ${page.data.length} item(s), next cursor: ${page.nextCursor ?? 'none'}`, ); const next = await page.nextPage(); if (!next) break; page = next; } ``` Python: ```python # One page at a time: `data` and `next_cursor`, or `next_page()` until it returns None. page = client.secrets.list(limit=2) n = 1 while page is not None: print(f"page {n}: {len(page.data)} item(s), next cursor: {page.next_cursor or 'none'}") page = page.next_page() n += 1 ``` ## In the SDKs List methods return a page you can read directly, and that is also an iterator over every item: it fetches further pages as the loop reaches them. TypeScript: ```typescript // Every item, fetching further pages as the loop reaches them: for await (const secret of client.secrets.list({ limit: 2 })) { console.log('secret:', secret.name); } ``` Python: ```python # Every item, fetching further pages as the loop reaches them: for secret in client.secrets.list(limit=2): print("secret:", secret["name"]) ``` The OpenAI-compatible GET /v1/models on the inference API follows OpenAI's shape instead: it returns every model in one response, with no cursor. --- # Platform events URL: https://hayonix.ai/docs/concepts/platform-events Webhook destinations that receive signed events when pods, jobs, models, batches, endpoints and billing change; verification, retries, pausing and secret rotation. ## What you receive A webhook destination is a URL in a project that receives platform events: a pod started or stopped, a fine-tuning job finished, a batch completed, a dedicated endpoint became ready, credit ran low. Each event is one POST with a JSON body: ```json { "id": "evt_…", "object": "event", "type": "pod.stopped", "version": "2026-11-01", "created_at": "2026-11-13T09:30:00.000Z", "org_id": "org_…", "project_id": "prj_…", "data": { "object": "pod", "id": "pod_…", "name": "trainer", "state": "stopped", "reason": "requested" } } ``` data names the resource (object, id) and carries the fields the event is about, with the same names the API uses. Fetch the resource by its ID when you need all of it. Events never carry secrets. GET /v1/webhooks/event-types lists every type, its product, and the JSON Schema of its data; a destination subscribes to a list of types or to ["*"]. | Event | Scope | When | | pod.running | project | The pod’s container is running (after a start, restart or a move to a new host). | | pod.stopped | project | The pod stopped and its compute was released (by request or for host maintenance); its volume is kept. | | pod.billing_stopped | project | The pod was stopped because the organization ran out of credit, reached a spend limit or was suspended. | | pod.terminated | project | The pod was terminated (deleted). It is not billed from now on. | | pod.preempted | project | An interruptible pod was preempted by on-demand work; it waits for capacity and restarts. | | pod.host_lost | project | The host running the pod stopped responding and was declared lost; the pod is kept and billing stops at the last proven second. | | volume.created | project | A volume was created. | | volume.deleted | project | A volume was deleted (its data is erased). | | file.validated | project | An uploaded file passed validation and can be used. | | file.rejected | project | An uploaded file failed validation; its validation report says why. | | serverless_endpoint.created | project | A serverless endpoint was created. | | serverless_endpoint.updated | project | A serverless endpoint’s settings or release changed. | | serverless_endpoint.deleted | project | A serverless endpoint was deleted; its queued jobs were cancelled. | | serverless_release.created | project | A new release of a serverless endpoint was created (a spec change or a rollback). | | fine_tune.succeeded | project | A fine-tuning job finished successfully. | | fine_tune.failed | project | A fine-tuning job failed. | | fine_tune.cancelled | project | A fine-tuning job was cancelled. | | fine_tune.stopped | project | A fine-tuning job was stopped by the platform (not enough credit for its plan, or billing enforcement). | | fine_tuned_model.available | project | A fine-tuned model is available (its job succeeded and its artefacts are stored). | | batch.in_progress | project | A batch passed validation and its requests started to run (request_counts.failed holds the invalid lines). | | batch.completed | project | A batch finished; its output file is ready. | | batch.failed | project | A batch failed (validation, or it stopped for a reason such as credit). | | batch.expired | project | A batch reached its completion window before every request ran. | | batch.cancelled | project | A batch was cancelled. | | sandbox.ready | project | A sandbox is running on its host and ready to run code. | | sandbox.ended | project | A sandbox ended (on request, at its deadline, when idle, or because of billing, a failure or its host); its files are gone. | | cluster.created | project | A cluster was created: every member was placed on a host and is starting. | | cluster.running | project | Every member of a cluster is running. | | cluster.degraded | project | A member of a cluster failed or lost its host. Nothing is restarted; the other members keep running and billing. | | cluster.stopped | project | A cluster’s members were stopped (out of credit, suspension or host maintenance); its shared volume is kept until it is deleted. | | cluster.deleted | project | A cluster was deleted; its members, network and shared volume are gone. | | evaluation.completed | project | An evaluation finished; its results file is ready. | | evaluation.stopped | project | An evaluation was stopped before every row ran (credit, spend limit or another stop reason); the results of the rows that ran are kept. | | evaluation.failed | project | An evaluation failed (its dataset was invalid, or too many rows errored). | | evaluation.cancelled | project | An evaluation was cancelled. | | dedicated_endpoint.ready | project | A dedicated endpoint has its first healthy replica and serves requests. | | dedicated_endpoint.inactivity_stopped | project | A dedicated endpoint was stopped after its inactivity timeout. | | dedicated_endpoint.failed | project | A dedicated endpoint’s replicas failed to start repeatedly; it has stopped trying until it is changed or restarted. | | billing.balance_low | org | Available credit fell below the low-balance threshold. | | billing.credit_exhausted | org | Available credit reached zero; new compute cannot launch. | | billing.compute_stopped | org | Running compute was stopped by billing enforcement. | | billing.payment_succeeded | org | A payment succeeded and its credit was added (a top-up or an auto-recharge). | | billing.payment_failed | org | A payment failed or was cancelled. | | billing.auto_recharge_failed | org | An automatic recharge failed and auto-recharge was turned off. | | api_key.created | project | An API key was created in the project (its secret is never included). | | api_key.revoked | project | An API key was revoked. | | webhook.test | project | A test event, sent on request to one destination only. | Organization events (billing.*: low balance, out of credit, compute stopped, payments, auto-recharge) concern the whole organization. A destination receives them only with org_events: true, which whoever sets it needs billing:read for (every member role has it; an API key needs the scope). ## Add a destination The response holds the signing secret (whs_…). It is shown only then (and when you rotate it), so store it with your receiver. curl: ```bash CREATED=$(curl -sS --fail-with-body "$API_BASE_URL/webhooks" \ -H "$AUTH" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \ -d '{"url": "https://hooks.example.com/platform", "description": "Ops alerts", "event_types": ["pod.stopped", "pod.host_lost", "fine_tune.succeeded"]}') WEBHOOK_ID=$(echo "$CREATED" | jq -r .id) SIGNING_SECRET=$(echo "$CREATED" | jq -r .secret) # shown only now: store it echo "created $WEBHOOK_ID ${SIGNING_SECRET:0:4}" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.create({ url: 'https://hooks.example.com/platform', description: 'Ops alerts', event_types: ['pod.stopped', 'pod.host_lost', 'fine_tune.succeeded', 'fine_tune.failed'], }); // Shown only now: store it where your receiver reads it (a secret manager, an env variable). const signingSecret = webhook.secret; console.log('created', webhook.id, signingSecret.slice(0, 4)); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.create( url="https://hooks.example.com/platform", description="Ops alerts", event_types=["pod.stopped", "pod.host_lost", "fine_tune.succeeded", "fine_tune.failed"], ) # Shown only now: store it where your receiver reads it (a secret manager, an env variable). signing_secret = webhook["secret"] print("created", webhook["id"], signing_secret[:4]) ``` Send a test event (webhook.test) to check your receiver, and read the delivery log with each attempt's status code, timing and the start of your response: curl: ```bash curl -sS --fail-with-body -X POST "$API_BASE_URL/webhooks/$WEBHOOK_ID/test" -H "$AUTH" | jq -r '"test delivery: \(.id) \(.status)"' curl -sS --fail-with-body "$API_BASE_URL/webhooks/$WEBHOOK_ID/deliveries?limit=20" -H "$AUTH" | jq -r '.data[] | "\(.event_type) \(.status) \(.attempts)"' ``` TypeScript: ```typescript const test = await client.webhooks.sendTest(webhook.id); console.log('test delivery:', test.id, test.status); for await (const d of client.webhooks.listDeliveries(webhook.id, { limit: 20 })) console.log(d.event_type, d.status, d.attempts, d.last_status_code); ``` Python: ```python test = client.webhooks.send_test(webhook["id"]) print("test delivery:", test["id"], test["status"]) for d in client.webhooks.list_deliveries(webhook["id"], limit=20): print(d["event_type"], d["status"], d["attempts"], d["last_status_code"]) ``` ## Verify every delivery | Header | Value | | Webhook-Id | The event ID (evt_…): the same on every retry and redelivery | | Webhook-Timestamp | When this attempt was signed, in Unix seconds | | Webhook-Signature | v1= and the hex HMAC-SHA256 of . with the secret; during a rotation, two such values separated by a space | | Webhook-Event | The event type | | Webhook-Delivery | The delivery (whd_…); a redelivery has a new one | A delivery is genuine when any v1 value matches and the timestamp is within five minutes of your clock. Both SDKs do this for you on the raw body: TypeScript: ```typescript import { constructWebhookEvent, WebhookVerificationError } from 'hayonix'; /** Your HTTP handler: `rawBody` is the request body exactly as received, before any parsing. */ async function handle( rawBody: string, headers: Record, secret: string, ): Promise { try { const event = await constructWebhookEvent({ secret, body: rawBody, headers }); // Deliveries can arrive more than once and in any order: dedupe on event.id (also the // Webhook-Id header), answer 2xx quickly, and do slow work afterwards. console.log('type:', event.type, 'id:', event.id); return 204; } catch (err) { if (err instanceof WebhookVerificationError) return 400; throw err; } } ``` Python: ```python from hayonix import WebhookVerificationError, construct_webhook_event def handle(raw_body: bytes, headers: dict[str, str], secret: str) -> int: """Your HTTP handler: raw_body is the request body exactly as received, before parsing.""" try: event = construct_webhook_event(secret, raw_body, headers) except WebhookVerificationError: return 400 # Deliveries can arrive more than once and in any order: dedupe on event["id"] (also the # Webhook-Id header), answer 2xx quickly, and do slow work afterwards. print("type:", event["type"], "id:", event["id"]) return 204 ``` ## Delivery, retries and pausing - Answer 2xx within 10 seconds. Redirects are never followed (a 3xx is a failure), and only the first kilobyte of your response is kept. - A failed attempt is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h and 8 h (a little jitter added): ten attempts over about 24 hours. Then the delivery is marked failed. - Delivery is at least once, and the order of events is not guaranteed: deduplicate on Webhook-Id, and compare the resource's current state when order matters. - A destination that has failed 20 attempts in a row and has not succeeded for 24 hours is paused: its waiting deliveries are given up, the organization's owners and admins get an email, and the audit log records it. Fix the receiver, send a test event, then resume it (PATCH /v1/webhooks/{webhook_id} with "status": "active") and redeliver what you missed. - Redelivering (POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver) sends the same event, with the same Webhook-Id, as a new delivery. - Deliveries and their payloads are kept for 30 days. - URLs that resolve to loopback, private, link-local or cloud-metadata addresses are refused when delivering, on the address actually connected to. ## Rotate the secret Rotating returns a new secret; the previous one keeps signing next to it for the overlap you choose (default 24 hours, up to a week; 0 revokes it at once). Deploy the new secret to your receiver within the overlap and no delivery fails verification. curl: ```bash curl -sS --fail-with-body -X POST "$API_BASE_URL/webhooks/$WEBHOOK_ID/rotate-secret" \ -H "$AUTH" -H "Content-Type: application/json" -d '{"overlap_seconds": 3600}' | jq -r '"new secret until the overlap ends: \(.previous_secret_expires_at)"' ``` TypeScript: ```typescript // The previous secret keeps signing (next to the new one) for an hour: deploy the new secret to // your receiver within that time and no delivery fails verification. const rotated = await client.webhooks.rotateSecret(webhook.id, { overlap_seconds: 3600 }); console.log('new secret until the overlap ends:', rotated.previous_secret_expires_at); ``` Python: ```python # The previous secret keeps signing (next to the new one) for an hour: deploy the new secret to # your receiver within that time and no delivery fails verification. rotated = client.webhooks.rotate_secret(webhook["id"], overlap_seconds=3600) print("new secret until the overlap ends:", rotated["previous_secret_expires_at"]) ``` --- # Webhooks and signatures URL: https://hayonix.ai/docs/concepts/webhooks Receive a signed HTTP callback when a serverless job finishes, verify its signature, and handle retries and duplicates. ## Completion webhooks A serverless endpoint can call your URL when each of its jobs finishes. Set webhook_url on the endpoint for every job, or on a single job when you submit it (null turns it off for that job). The delivery is a POST with a JSON body: ```json { "id": "whd_…", "object": "event", "type": "serverless.job.finished", "created_at": "2026-01-01T00:00:00.000Z", "data": { "object": "serverless_job", "id": "sjb_…", "state": "succeeded", "output": { … } } } ``` data is the job as GET /v1/serverless/jobs/{job_id} returns it. ## Verify the signature Each delivery is signed with the endpoint's webhook secret (whs_…), returned once when the endpoint is created and again when you rotate it (POST /v1/serverless/endpoints/{endpoint_id}/rotate-webhook-secret). Three headers come with it: | Header | Value | | Webhook-Id | The delivery ID (whd_…), the same on every retry of the delivery | | Webhook-Timestamp | When this attempt was signed, in Unix seconds | | Webhook-Signature | v1= and the hex HMAC-SHA256 of . with the secret | To verify: compute the HMAC over the timestamp, a dot and the raw request body (before any JSON parsing), compare it with the header in constant time, and reject a timestamp more than five minutes from your clock, so a captured delivery cannot be replayed later. TypeScript: ```typescript import { createHmac, timingSafeEqual } from 'node:crypto'; /** True when `body` (the raw request body, unparsed) was signed with `secret` recently. */ export function verifyWebhook( secret: string, headers: { 'webhook-signature': string; 'webhook-timestamp': string }, body: string, toleranceSeconds = 300, ): boolean { const timestamp = Number(headers['webhook-timestamp']); if (!Number.isInteger(timestamp)) return false; if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false; // replayed const expected = `v1=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`; const given = headers['webhook-signature'].trim(); return ( expected.length === given.length && timingSafeEqual(Buffer.from(expected), Buffer.from(given)) ); } ``` Python: ```python import hashlib import hmac import time def verify_webhook(secret: str, headers: dict[str, str], body: bytes, tolerance_seconds: int = 300) -> bool: """True when `body` (the raw request body, unparsed) was signed with `secret` recently.""" try: timestamp = int(headers["webhook-timestamp"]) except (KeyError, ValueError): return False if abs(time.time() - timestamp) > tolerance_seconds: return False # too old: possibly replayed digest = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest() return hmac.compare_digest(f"v1={digest}", headers.get("webhook-signature", "").strip()) ``` ## Retries and duplicates Answer with any 2xx status within 10 seconds to acknowledge a delivery. Any other answer, a timeout or a network error is retried with exponential backoff, up to 8 attempts, after which the delivery is marked failed. GET /v1/serverless/endpoints/{endpoint_id}/webhook-deliveries shows every delivery and its attempts. A delivery can arrive more than once (your answer may be lost on the way back), so deduplicate on Webhook-Id. Acknowledge quickly and do slow work afterwards. Destinations must be public: URLs that resolve to private, loopback or link-local addresses are refused. When you rotate the secret, the old one stops signing at once: deploy the new secret to your receiver before or right after you rotate. --- # TypeScript SDK URL: https://hayonix.ai/docs/sdks/typescript Install and configure the hayonix package, handle errors, tune retries and timeouts, paginate, stream, upload and download files, wait for resources and work with money. The TypeScript SDK has a method for every operation in the API reference, grouped by area: client.pods.create, client.serverless.submitJob, client.fineTuning.listEvents. Each reference page shows its call. Responses are typed plain objects in the API's own snake_case field names. ## Install ```sh npm install hayonix ``` Inference goes through the official openai package; install it next to the SDK if you call models: ```sh npm install openai ``` ## Configure new Client() reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL from the environment. Pass any of them as options instead (apiKey, baseUrl, inferenceBaseUrl), along with timeout, maxRetries, maxRetryWaitMs, defaultHeaders or your own fetch. TypeScript: ```typescript import { Client } from 'hayonix'; // API_KEY, API_BASE_URL and INFERENCE_BASE_URL come from the environment by default. const client = new Client({ timeout: 30_000, // per attempt, in milliseconds (default 60 000) maxRetries: 3, // retries of a retryable failure (default 2) }); const me = await client.caller(); // the key's org, project and permissions console.log('project:', me.project_id); ``` Path parameters are positional and everything else goes in one params object: client.pods.exec(podId, { command }). Organization-level calls fill in the key's organization, so client.billing.getBalance() needs no arguments. ## Errors Every API error is an ApiError subclass chosen by the error's type; see Errors and retries for the full list. TypeScript: ```typescript import { ApiError, NotFoundError, RateLimitError } from 'hayonix'; try { await client.pods.get('pod_00000000000000000000000000'); } catch (err) { if (err instanceof NotFoundError) { console.log('not found:', err.message); } else if (err instanceof RateLimitError) { console.log('slow down; retry after', err.retryAfterSeconds, 's'); } else if (err instanceof ApiError) { console.log(err.status, err.type, err.code, err.param, 'request', err.requestId); } else { throw err; } } ``` ## Retries, timeouts and cancellation The last argument of every method takes per-call options: timeout (milliseconds per attempt), maxRetries, signal (an AbortSignal that cancels the call and its retries), idempotencyKey and extra headers. TypeScript: ```typescript const controller = new AbortController(); const secrets = await client.secrets.list( { limit: 10 }, { timeout: 5_000, maxRetries: 0, signal: controller.signal }, ); console.log('secrets on the first page:', secrets.data.length); ``` What is retried, and when, is described in Errors and retries. Creating calls carry an Idempotency-Key the SDK generates and keeps across its retries; pass idempotencyKey to make a retry from another process safe too: TypeScript: ```typescript import { randomUUID } from 'node:crypto'; import { Client, IdempotencyError } from 'hayonix'; const client = new Client(); const key = randomUUID(); // store it with the work item, so a restarted job reuses it const first = await client.secrets.create( { name, value: 'example-value' }, { idempotencyKey: key }, ); const again = await client.secrets.create( { name, value: 'example-value' }, { idempotencyKey: key }, ); console.log('same secret:', first.id === again.id); ``` ## Pagination List methods return a page that you can await (data, nextCursor, nextPage()) or iterate with for await over every item. TypeScript: ```typescript // Every item, fetching further pages as the loop reaches them: for await (const secret of client.secrets.list({ limit: 2 })) { console.log('secret:', secret.name); } ``` TypeScript: ```typescript // One page at a time: `data` and `nextCursor`, or `nextPage()` until it returns null. let page = await client.secrets.list({ limit: 2 }); for (let n = 1; ; n++) { console.log( `page ${n}: ${page.data.length} item(s), next cursor: ${page.nextCursor ?? 'none'}`, ); const next = await page.nextPage(); if (!next) break; page = next; } ``` ## Uploads and downloads A file field accepts a Blob, a File, bytes, a string, or { name, data }. In Node, fileFromPath from hayonix/node streams a file from disk. Downloads return a BinaryResponse: read it once with text(), bytes(), body (a web stream) or saveTo(path). TypeScript: ```typescript import { fileFromPath } from 'hayonix/node'; // Upload from disk (streamed, not read into memory), wait for validation, download again. const uploaded = await client.files.upload({ file: await fileFromPath(path), purpose: 'batch' }); const checked = await client.waitFor.file(uploaded.id); console.log('file', checked.id, checked.status, checked.bytes, 'bytes'); const content = await client.files.getContent(uploaded.id); await content.saveTo(join(dir, 'copy.jsonl')); ``` ## Waiting client.waitFor polls a resource until it reaches the state you want, with a default timeout per kind: pod (until running, or another state you pass), job, fineTune, batch, file, dedicatedEndpoint, sandbox and cluster (until every member runs). Each throws WaitTimeoutError when time runs out and UnexpectedStateError when the resource reaches a state it cannot leave for the one you asked for. onUpdate sees every observation. TypeScript: ```typescript const done = await client.waitFor.batch(batch.id, { onUpdate: (b) => { console.log('status:', b.status); }, }); ``` ## Streaming Inference streams come from the OpenAI client. Serverless job output and fine-tuning events are followed with client.follow, as async iterables that end when the job does: TypeScript: ```typescript const job = await client.serverless.submitJob(endpoint.id, { input: { text: 'hello from a worker' }, }); for await (const chunk of client.follow.jobStream(job.id)) { console.log('chunk:', JSON.stringify(chunk.data)); } const done = await client.waitFor.job(job.id); console.log('state:', done.state, 'output:', JSON.stringify(done.output)); ``` Pod logs are a server-sent event stream: client.pods.streamLogs(podId, { follow: 'true' }) resolves to an iterable of events. ## Money Amounts are nano-USD decimal strings. Keep them as strings or bigints; the helpers format and parse them without floating point. TypeScript: ```typescript import { formatCost, formatUsd, parseUsd } from 'hayonix'; const balance = await client.billing.getBalance(); // the key's org is filled in for you console.log('available:', formatUsd(balance.available)); // e.g. "$25.00" console.log('exact:', formatUsd(balance.available, { maxDecimals: 9 })); console.log('a tiny charge:', formatCost('184331')); // "<$0.01" console.log('$5 in nano-USD:', parseUsd('5')); // "5000000000" ``` ## The OpenAI client await client.openai() returns the official OpenAI client pointed at the inference base URL with your key. Everything the inference API offers is used through it unchanged. TypeScript: ```typescript import { Client } from 'hayonix'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const client = new Client(); // reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL const openai = await client.openai(); const completion = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Name three uses for a GPU in one sentence.' }], max_completion_tokens: 64, }); console.log('reply:', completion.choices[0]?.message.content?.trim() ?? ''); console.log('tokens:', completion.usage?.total_tokens); ``` --- # Python SDK URL: https://hayonix.ai/docs/sdks/python Install and configure the hayonix package (sync and async), handle errors, tune retries and timeouts, paginate, stream, upload and download files, wait for resources and work with money. The Python SDK has a method for every operation in the API reference, in snake_case: client.pods.create, client.serverless.submit_job, client.fine_tuning.list_events. Responses are plain dictionaries, typed as TypedDicts in hayonix.types. It needs Python 3.11 or later. ## Install ```sh pip install "hayonix[openai]" ``` ## Configure Client() reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL from the environment; keyword arguments override them (api_key, base_url, inference_base_url), along with timeout (seconds), max_retries, max_retry_wait, default_headers and your own http_client. Use it as a context manager, or call close(), to release its connections. Python: ```python from hayonix import Client # API_KEY, API_BASE_URL and INFERENCE_BASE_URL come from the environment by default. client = Client( timeout=30.0, # seconds per network operation of an attempt (default 60) max_retries=3, # retries of a retryable failure (default 2) ) me = client.caller() # the key's org, project and permissions print("project:", me["project_id"]) ``` Path parameters are positional and everything else is a keyword argument: client.pods.exec(pod_id, command=[…]). Leaving an argument out omits it; None sends JSON null. Organization-level calls fill in the key's organization. ## Errors Every API error is an ApiError subclass chosen by the error's type; see Errors and retries. Python: ```python from hayonix import ApiError, NotFoundError, RateLimitError try: client.pods.get("pod_00000000000000000000000000") except NotFoundError as err: print("not found:", err.message) except RateLimitError as err: print("slow down; retry after", err.retry_after_seconds, "s") except ApiError as err: print(err.status, err.type, err.code, err.param, "request", err.request_id) ``` ## Retries and timeouts Per-call settings go in request_options: timeout, max_retries, idempotency_key and headers. Python: ```python secrets = client.secrets.list(limit=10, request_options={"timeout": 5.0, "max_retries": 0}) print("secrets on the first page:", len(secrets.data)) ``` Retries follow the rules in Errors and retries. Creating calls keep one Idempotency-Key across their retries; pass your own for retries from another process: Python: ```python import uuid from hayonix import Client, IdempotencyError client = Client() key = str(uuid.uuid4()) # store it with the work item, so a restarted job reuses it first = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key}) again = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key}) print("same secret:", first["id"] == again["id"]) ``` ## Pagination List methods return a page (data, next_cursor, next_page()) that is also an iterator over every item. Python: ```python # Every item, fetching further pages as the loop reaches them: for secret in client.secrets.list(limit=2): print("secret:", secret["name"]) ``` Python: ```python # One page at a time: `data` and `next_cursor`, or `next_page()` until it returns None. page = client.secrets.list(limit=2) n = 1 while page is not None: print(f"page {n}: {len(page.data)} item(s), next cursor: {page.next_cursor or 'none'}") page = page.next_page() n += 1 ``` ## Uploads and downloads A file argument accepts a pathlib.Path (streamed from disk), bytes, a binary file object, or a (filename, content) tuple. Downloads return a BinaryResponse: read(), text(), iter_bytes() or save(path). Python: ```python # Upload from disk (streamed, not read into memory), wait for validation, download again. uploaded = client.files.upload(file=path, purpose="batch") checked = client.wait_for.file(uploaded["id"]) print("file", checked["id"], checked["status"], checked["bytes"], "bytes") client.files.get_content(uploaded["id"]).save(pathlib.Path(tmp) / "copy.jsonl") ``` ## Waiting client.wait_for polls until a resource reaches a state: pod, job, fine_tune, batch, file, dedicated_endpoint, sandbox and cluster, with timeout and on_update. It raises WaitTimeoutError or UnexpectedStateError. Python: ```python done = client.wait_for.batch(batch["id"], on_update=lambda b: print("status:", b["status"])) ``` ## Streaming client.follow.job_stream and client.follow.fine_tune_events iterate live output until the job ends: Python: ```python job = client.serverless.submit_job(endpoint["id"], input={"text": "hello from a worker"}) for chunk in client.follow.job_stream(job["id"]): print("chunk:", json.dumps(chunk.get("data"))) done = client.wait_for.job(job["id"]) print("state:", done["state"], "output:", json.dumps(done.get("output"))) ``` ## Money Python: ```python from hayonix import format_cost, format_usd, parse_usd balance = client.billing.get_balance() # the key's org is filled in for you print("available:", format_usd(balance["available"])) # e.g. "$25.00" print("exact:", format_usd(balance["available"], max_decimals=9)) print("a tiny charge:", format_cost("184331")) # "<$0.01" print("$5 in nano-USD:", parse_usd("5")) # "5000000000" ``` ## Async AsyncClient has the same methods as coroutines. Its list methods return a page you can await for the first page or iterate with async for. Python: ```python from hayonix import AsyncClient async def main() -> None: async with AsyncClient() as aclient: async for secret in aclient.secrets.list(limit=50): print("secret:", secret["name"]) balance = await aclient.billing.get_balance() print("available:", format_usd(balance["available"])) asyncio.run(main()) ``` ## The OpenAI client client.openai() (and AsyncClient.openai()) returns the official OpenAI client pointed at the inference base URL. It needs the openai extra: ```sh pip install "hayonix[openai]" ``` Python: ```python import os from hayonix import Client model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") client = Client() # reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL openai = client.openai() completion = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Name three uses for a GPU in one sentence."}], max_completion_tokens=64, ) print("reply:", (completion.choices[0].message.content or "").strip()) print("tokens:", completion.usage.total_tokens if completion.usage else None) ``` --- # Use the SDK you already have URL: https://hayonix.ai/docs/sdks/compatible-sdks Point the OpenAI SDK (chat completions or the Responses API) or the Anthropic SDK (the Messages API) at the inference API by changing only the base URL and the key: what each shape supports and what it refuses. The inference API answers three request shapes. Each is the shape an official SDK already speaks, so an application written for one of them runs here with two changes: the base URL and an API key of yours. Model names are this platform's catalog IDs (publisher/name, listed by GET /v1/models); another vendor's model name is answered with a plain "not served here". - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 | Shape | Route | SDK | Base URL to give the SDK | | Chat completions | POST /v1/chat/completions | openai (Python, TypeScript) | the inference base URL, with /v1 | | Responses | POST /v1/responses | openai (Python, TypeScript) | the inference base URL, with /v1 | | Messages | POST /v1/messages | anthropic (Python), @anthropic-ai/sdk (TypeScript) | the inference host, without /v1 (the SDK adds it) | All three run on the same path underneath: the same key, the same credit check (402 when your balance cannot cover the worst case), the same per-minute request and token limits with the same rate-limit headers, the same replicas and the same per-token prices. A request is billed once, on the tokens the model reported, whichever shape it came in; usage and cost analytics show which route it came through. Fine-tuned models, shared models and dedicated endpoints work in every shape. ## Chat completions The OpenAI-compatible chat API, described in full in the inference API reference. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, messages: [{role: "user", content: "Name one use for a GPU, in five words."}], max_completion_tokens: 32 }' | curl -sS "$INFERENCE_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | jq -r '"chat: " + (.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; ""))' ``` TypeScript: ```typescript import OpenAI from 'openai'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const openai = new OpenAI({ apiKey: process.env.API_KEY, baseURL: process.env.INFERENCE_BASE_URL, // e.g. https://api.example.com/v1 }); const completion = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Name one use for a GPU, in five words.' }], max_completion_tokens: 32, }); console.log('chat:', completion.choices[0]?.message.content?.trim() ?? ''); ``` Python: ```python import os from openai import OpenAI model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") openai = OpenAI( api_key=os.environ["API_KEY"], base_url=os.environ["INFERENCE_BASE_URL"], # e.g. https://api.example.com/v1 ) completion = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Name one use for a GPU, in five words."}], max_completion_tokens=32, ) print("chat:", (completion.choices[0].message.content or "").strip()) ``` ## Responses client.responses.create and client.responses.stream work unchanged, streaming or not, including the SDK's event helpers and responses.parse for structured output. curl: ```bash RESPONSE=$(jq -n --arg model "$MODEL" '{ model: $model, instructions: "Answer in one short sentence.", input: "My favourite colour is green. What is a GPU?", max_output_tokens: 48 }' | curl -sS "$INFERENCE_BASE_URL/responses" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @-) RESPONSE_ID=$(jq -r .id <<<"$RESPONSE") jq -r '"responses: " + ([.output[] | select(.type == "message") | .content[].text] | join("") | gsub("^\\s+|\\s+$"; ""))' <<<"$RESPONSE" jq -n --arg model "$MODEL" --arg prev "$RESPONSE_ID" '{ model: $model, previous_response_id: $prev, input: "What is my favourite colour? One word.", max_output_tokens: 8, store: false }' | curl -sS "$INFERENCE_BASE_URL/responses" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | jq -r '"continued: " + ([.output[] | select(.type == "message") | .content[].text] | join("") | gsub("^\\s+|\\s+$"; ""))' curl -sS -X DELETE "$INFERENCE_BASE_URL/responses/$RESPONSE_ID" \ -H "Authorization: Bearer $API_KEY" | jq -r '"deleted: \(.id)"' ``` TypeScript: ```typescript import OpenAI from 'openai'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const openai = new OpenAI({ apiKey: process.env.API_KEY, baseURL: process.env.INFERENCE_BASE_URL, // e.g. https://api.example.com/v1 }); const response = await openai.responses.create({ model, instructions: 'Answer in one short sentence.', input: 'My favourite colour is green. What is a GPU?', max_output_tokens: 48, }); console.log('responses:', response.output_text.trim()); // Stored responses continue a conversation without resending it. const followUp = await openai.responses.create({ model, previous_response_id: response.id, input: 'What is my favourite colour? One word.', max_output_tokens: 8, }); console.log('continued:', followUp.output_text.trim()); // Streaming: the SDK's event helpers work unchanged. const stream = openai.responses.stream({ model, input: 'Count from one to five.', max_output_tokens: 32, }); stream.on('response.output_text.delta', (e) => process.stdout.write(e.delta)); await stream.finalResponse(); process.stdout.write('\n'); // Stored responses are kept for 30 days; delete them when you are done. await openai.responses.delete(followUp.id); await openai.responses.delete(response.id); ``` Python: ```python import os from openai import OpenAI model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") openai = OpenAI( api_key=os.environ["API_KEY"], base_url=os.environ["INFERENCE_BASE_URL"], # e.g. https://api.example.com/v1 ) response = openai.responses.create( model=model, instructions="Answer in one short sentence.", input="My favourite colour is green. What is a GPU?", max_output_tokens=48, ) print("responses:", response.output_text.strip()) # Stored responses continue a conversation without resending it. follow_up = openai.responses.create( model=model, previous_response_id=response.id, input="What is my favourite colour? One word.", max_output_tokens=8, ) print("continued:", follow_up.output_text.strip()) # Streaming: iterate the events. with openai.responses.stream( model=model, input="Count from one to five.", max_output_tokens=32 ) as stream: for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) print() # Stored responses are kept for 30 days; delete them when you are done. openai.responses.delete(follow_up.id) openai.responses.delete(response.id) ``` Stored responses. A response is stored for its project unless you send store: false: read it back with GET /v1/responses/{id}, list what it was asked with GET /v1/responses/{id}/input_items, continue the conversation with previous_response_id (the earlier turns are sent to the model again and billed as input tokens, as any conversation is), and delete it with DELETE /v1/responses/{id}. Stored responses are encrypted at rest, visible to their own project only, and deleted 30 days after they were created. Storing needs the stored_response:create permission (continuing needs stored_response:read): a key without it gets its answer with store: false, and one that asks for store: true explicitly is refused. A response that failed or was cut off is never stored. Responses sent as lines of a batch are never stored. | | Responses | | Supported | input as text or items (message with input_text and input_image parts, function_call, function_call_output); instructions; function tools, tool_choice (none, auto, required, a function), parallel_tool_calls; text.format (text, json_object, json_schema); max_output_tokens, temperature, top_p; metadata; stream; store and previous_response_id; batches (/v1/responses as a batch endpoint) | | Refused, naming the parameter | reasoning and text.verbosity (reasoning-model settings); hosted tools (any tool type other than function: web search, file search, code interpreter, computer use, MCP, image generation, shell); background; conversation; reusable prompt; include; max_tool_calls; top_logprobs; truncation: auto; service tiers other than the default; item_reference, reasoning and file inputs; POST /v1/responses/{id}/cancel and /v1/responses/input_tokens; any unknown parameter | | Accepted and ignored | user, safety_identifier, prompt_cache_key, prompt_cache_retention (prompt caching is automatic here), stream_options | A response that reaches max_output_tokens is incomplete with incomplete_details.reason max_output_tokens. A stream ends with response.completed, response.incomplete or, when the model fails mid-stream, response.failed. ## Messages client.messages.create and client.messages.stream work unchanged, with your key passed as the SDK's API key (it is sent in x-api-key; Authorization: Bearer works too). Errors on this route use that API's error shape ({"type": "error", "error": {"type", "message"}, "request_id"}) and status codes, so the SDK raises its usual exceptions; request-id is set on every answer. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, max_tokens: 48, system: "Answer in one short sentence.", messages: [{role: "user", content: "What is a GPU?"}] }' | curl -sS "$INFERENCE_BASE_URL/messages" \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d @- | jq -r '"messages: " + ([.content[] | select(.type == "text") | .text] | join("") | gsub("^\\s+|\\s+$"; "")) + " (\(.stop_reason))"' ``` TypeScript: ```typescript import Anthropic from '@anthropic-ai/sdk'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const anthropic = new Anthropic({ apiKey: process.env.API_KEY, // The host only: this SDK adds /v1/messages itself. baseURL: process.env.INFERENCE_BASE_URL?.replace(/\/v1$/, ''), }); const message = await anthropic.messages.create({ model, max_tokens: 48, system: 'Answer in one short sentence.', messages: [{ role: 'user', content: 'What is a GPU?' }], }); const text = message.content .map((b) => (b.type === 'text' ? b.text : '')) .join('') .trim(); console.log( 'messages:', text, `(${message.stop_reason}, ${String(message.usage.output_tokens)} tokens)`, ); const live = anthropic.messages.stream({ model, max_tokens: 32, messages: [{ role: 'user', content: 'Count from one to five.' }], }); live.on('text', (t) => process.stdout.write(t)); await live.finalMessage(); process.stdout.write('\n'); ``` Python: ```python import os from anthropic import Anthropic model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") anthropic = Anthropic( api_key=os.environ["API_KEY"], # The host only: this SDK adds /v1/messages itself. base_url=os.environ["INFERENCE_BASE_URL"].removesuffix("/v1"), ) message = anthropic.messages.create( model=model, max_tokens=48, system="Answer in one short sentence.", messages=[{"role": "user", "content": "What is a GPU?"}], ) text = "".join(block.text for block in message.content if block.type == "text").strip() print("messages:", text, f"({message.stop_reason}, {message.usage.output_tokens} tokens)") with anthropic.messages.stream( model=model, max_tokens=32, messages=[{"role": "user", "content": "Count from one to five."}], ) as live: for chunk in live.text_stream: print(chunk, end="", flush=True) print() ``` The anthropic-version header is required (the SDKs send it). Versions 2023-06-01 and 2026-10-21 are implemented and the version is recorded with each request; any other is refused. Version 2026-10-21 (what current SDKs send) has no temperature, top_p or top_k, and refuses them as that API does; send anthropic-version: 2023-06-01 to use them. anthropic-beta headers are refused: beta features of that API are not offered. | | Messages | | Supported | system (text or text blocks) and system turns; messages with text, image (base64 or URL), tool_use and tool_result blocks; custom tools (name, description, input_schema, strict), tool_choice (auto, any, tool, none, disable_parallel_tool_use); output_config.format (JSON schema); max_tokens, stop_sequences; under 2023-06-01, temperature, top_p, top_k; metadata.user_id; stream | | Refused, naming the parameter | extended thinking (thinking other than {"type": "disabled"}) and output_config.effort; server tools (any tool with a type other than custom: web search, web fetch, code execution, bash, text editor, computer use, memory, tool search); MCP servers; container; context_management; document, search-result and thinking blocks; file image sources; citations; inference_geo; speed: fast; workspace_id, user_profile_id, diagnostics; token counting (/v1/messages/count_tokens: usage in every answer is the exact count); that API's message batches (use /v1/batches); any unknown parameter | | Accepted and ignored | cache_control anywhere (prompt caching is automatic here, and cache_read_input_tokens reports what it saved), metadata.user_id, service_tier, speed: standard, eager_input_streaming | stop_reason is end_turn, max_tokens, tool_use or stop_sequence; on engines that do not report which stop sequence matched, a stop sequence ends the turn as end_turn with stop_sequence: null. A tool_result with is_error reaches the model prefixed Error:. usage.input_tokens excludes cached input, which is cache_read_input_tokens. A stream that fails mid-way ends with an error event. --- # Command-line tool URL: https://hayonix.ai/docs/sdks/cli Install the hayonix command, sign in, script it with --json and -q, set up shell completion, and read its exit codes. hayonix covers the everyday work (pods, serverless endpoints and jobs, dedicated endpoints, files, fine-tunes, batches, models, chat, secrets, SSH keys, balance and usage) with readable output, and reaches every other API operation through hayonix api. Run hayonix --help, or --help after any command, for its arguments and flags. ## Install It needs Node.js 24 or later. ```sh npm install -g hayonix-cli ``` ## Sign in login reads a project API key (from a hidden prompt, or from stdin with --with-key-stdin), checks it with the API and stores it with the base URL in your config directory, readable only by you. whoami shows the org, project and permissions in use. CLI: ```bash echo "$KEY" | hayonix login --with-key-stdin # or `platform login` for a hidden prompt hayonix whoami ``` The key is taken from --api-key, else API_KEY, else the stored login; the API URL from --base-url, else API_BASE_URL, else the stored one. Inference commands use INFERENCE_BASE_URL when it is set. hayonix logout removes the stored key. ## Output for people and for scripts By default commands print tables and summaries. Two global flags, accepted anywhere on the line, change that: - --json prints the API's JSON response on stdout, and errors as the JSON error envelope on stderr; - -q (--quiet) prints only IDs, one per line, which is what you capture in a variable. CLI: ```bash hayonix secrets list # a table for people hayonix secrets list --json | jq . # the API's JSON, for scripts hayonix balance ``` CLI: ```bash SECRET_ID=$(echo "example" | hayonix secrets create --name CLI_DEMO --value-stdin -q) # only the ID hayonix secrets delete "$SECRET_ID" -y ``` Destructive commands ask for confirmation at a terminal; pass -y in scripts. Commands that start long work take --wait (or --follow), limited by --wait-timeout. ## Any operation: hayonix api hayonix api calls any operation in the API reference by its SDK name (pods.list) or operation ID (listPods). Path parameters are arguments; other inputs are --param name=value (name:=json for a JSON value, name=@path for a file) or a whole --body. Every reference page shows its api call. CLI: ```bash hayonix api secrets.list --param limit=5 # any operation, by SDK name or operation ID hayonix api getBalance --json | jq -r .available ``` ## Exit codes | Code | Meaning | | 0 | Success | | 1 | The API returned an error, or the command failed | | 2 | Usage error: unknown command or flag, a missing or malformed value | | 3 | Not signed in, or the API key was refused or lacks permission | | 4 | Not found | | 5 | Gave up waiting (--wait, --follow, serverless run) | | 6 | The awaited work did not succeed (a job, fine-tune, batch, pod or file) | | 130 | Interrupted | CLI: ```bash if platform pods show pod_00000000000000000000000000 2>/dev/null; then echo "found" else echo "exit code $?" # 4: not found fi ``` ## Shell completion hayonix completion bash, zsh or fish prints a completion script for commands and flags. Load it from your shell's startup file. CLI: ```bash hayonix completion bash > /dev/null # load it with: source <(hayonix completion bash) ``` ## Other global flags --timeout sets the per-request timeout (30s), --debug logs each request line to stderr (never the key), and --no-color (or the NO_COLOR environment variable) turns colour off. --- # Inference API (OpenAI-compatible) URL: https://hayonix.ai/docs/reference/inference The OpenAI-compatible routes: chat completions, completions, embeddings, rerank and models, with authentication, billing, limits and errors. The inference API follows the OpenAI API: request and response bodies have OpenAI's shape, so the official OpenAI SDKs and tools built on them work by changing the base URL and the key. It is served at INFERENCE_BASE_URL: - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 Authenticate with a project API key that has the inference:invoke scope, as Authorization: Bearer sk_…. ## Routes | Method | Path | What it does | | POST | /v1/chat/completions | A chat completion, optionally streamed | | POST | /v1/completions | A text completion, optionally streamed (chat and completion models) | | POST | /v1/embeddings | Embeddings for one input or a list | | POST | /v1/rerank | Documents ordered by relevance to a query | | GET | /v1/models | Every model your key can use | | GET | /v1/models/{model} | One model | Each model has a type (chat, completion, embedding or rerank), and a route accepts only models of the types it serves: a chat model answers /v1/chat/completions and /v1/completions; an embedding model answers /v1/embeddings. ## Chat completions and completions Send the OpenAI request body. The gateway reads only what it needs (model, stream, max_tokens or max_completion_tokens, n) and passes everything else (tools, response_format, sampling parameters, logprobs, image parts) to the engine unchanged. Which of those a model supports is listed in its capabilities. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, messages: [{role: "user", content: "Name three uses for a GPU in one sentence."}], max_completion_tokens: 64 }' | curl -sS "$INFERENCE_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | jq -r '"reply: " + (.choices[0].message.content // "" | gsub("^\\s+|\\s+$"; "")), "tokens: \(.usage.total_tokens)"' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const model = process.env.MODEL ?? 'qwen/qwen2.5-0.5b-instruct'; const client = new Client(); // reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL const openai = await client.openai(); const completion = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Name three uses for a GPU in one sentence.' }], max_completion_tokens: 64, }); console.log('reply:', completion.choices[0]?.message.content?.trim() ?? ''); console.log('tokens:', completion.usage?.total_tokens); ``` Python: ```python import os from hayonix import Client model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct") client = Client() # reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL openai = client.openai() completion = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Name three uses for a GPU in one sentence."}], max_completion_tokens=64, ) print("reply:", (completion.choices[0].message.content or "").strip()) print("tokens:", completion.usage.total_tokens if completion.usage else None) ``` CLI: ```bash hayonix models list # The reply goes to stdout, the token count to stderr (shown here with 2>&1). hayonix chat "$MODEL" "Name three uses for a GPU in one sentence." --max-tokens 64 --no-stream 2>&1 ``` With "stream": true the answer arrives as server-sent events, one data: line per chunk, ending with data: [DONE]. Add "stream_options": {"include_usage": true} to receive a final chunk with the token counts. curl: ```bash jq -n --arg model "$MODEL" '{ model: $model, messages: [{role: "user", content: "Count from one to five."}], max_completion_tokens: 64, stream: true }' | curl -sS -N "$INFERENCE_BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d @- | sed -un 's/^data: //p' | grep --line-buffered -v '^\[DONE\]$' | jq -j '.choices[0].delta.content // empty' echo ``` TypeScript: ```typescript const stream = await openai.chat.completions.create({ model, messages: [{ role: 'user', content: 'Count from one to five.' }], max_completion_tokens: 64, stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta.content ?? ''); } process.stdout.write('\n'); ``` Python: ```python stream = openai.chat.completions.create( model=model, messages=[{"role": "user", "content": "Count from one to five."}], max_completion_tokens=64, stream=True, ) for chunk in stream: if chunk.choices: print(chunk.choices[0].delta.content or "", end="", flush=True) print() ``` CLI: ```bash hayonix chat "$MODEL" "Count from one to five." --max-tokens 64 # streams by default ``` ## Embeddings curl: ```bash jq -n --arg model "$EMBEDDING_MODEL" '{model: $model, input: ["a red bicycle", "a blue car"]}' | curl -sS --fail-with-body "$INFERENCE_BASE_URL/embeddings" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- | jq -r '.data[] | "embedding \(.index): \(.embedding | length) dimensions"' ``` TypeScript: ```typescript const embeddingModel = process.env.EMBEDDING_MODEL ?? 'baai/bge-small-en-v1.5'; const embeddings = await openai.embeddings.create({ model: embeddingModel, input: ['a red bicycle', 'a blue car'], }); for (const e of embeddings.data) console.log(`embedding ${e.index}: ${e.embedding.length} dimensions`); ``` Python: ```python embedding_model = os.environ.get("EMBEDDING_MODEL", "baai/bge-small-en-v1.5") embeddings = openai.embeddings.create(model=embedding_model, input=["a red bicycle", "a blue car"]) for e in embeddings.data: print(f"embedding {e.index}: {len(e.embedding)} dimensions") ``` ## Rerank Not part of the OpenAI API, so call it directly. The body has model, query, documents (1 to 1000 strings, or objects with a text field), optionally top_n and return_documents. Results come back best first, each with the document's index in your list and its relevance_score; return_documents: true adds the document text. curl: ```bash jq -n --arg model "$RERANK_MODEL" '{ model: $model, query: "How do I stop paying for a pod?", documents: ["Terminate the pod to stop billing.", "Pods run containers.", "Volumes keep data."], top_n: 2 }' | curl -sS --fail-with-body "$INFERENCE_BASE_URL/rerank" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- | jq -r '.results[] | "document \(.index): score \(.relevance_score)"' ``` TypeScript: ```typescript const rerankModel = process.env.RERANK_MODEL ?? 'cross-encoder/ms-marco-minilm-l6-v2'; // Rerank is not part of the OpenAI client; call the route directly. const res = await fetch(`${client.inferenceBaseUrl}/rerank`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: rerankModel, query: 'How do I stop paying for a pod?', documents: ['Terminate the pod to stop billing.', 'Pods run containers.', 'Volumes keep data.'], top_n: 2, }), }); if (!res.ok) throw new Error(`rerank failed: ${res.status} ${await res.text()}`); const ranked = (await res.json()) as { results: { index: number; relevance_score: number }[] }; for (const r of ranked.results) console.log(`document ${r.index}: score ${r.relevance_score}`); ``` Python: ```python # Rerank is not part of the OpenAI client; call the route directly. import httpx rerank_model = os.environ.get("RERANK_MODEL", "cross-encoder/ms-marco-minilm-l6-v2") res = httpx.post( f"{client.inference_base_url}/rerank", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, json={ "model": rerank_model, "query": "How do I stop paying for a pod?", "documents": ["Terminate the pod to stop billing.", "Pods run containers.", "Volumes keep data."], "top_n": 2, }, ) res.raise_for_status() for r in res.json()["results"]: print(f"document {r['index']}: score {r['relevance_score']}") ``` ## Models GET /v1/models returns OpenAI's list shape ({"object": "list", "data": [...]}, every model in one response) with extra fields on each model: type, display_name, context_length, capabilities, pricing and serving. serving is true when a replica is running the model right now; the catalog also lists models that are not served, such as base models for fine-tuning. Your project's private models (fine-tunes, dedicated endpoints) are listed only for your project. curl: ```bash curl -sS --fail-with-body "$INFERENCE_BASE_URL/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[] | "\(.id) type=\(.type) serving=\(.serving)"' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const openai = await client.openai(); for await (const model of openai.models.list()) { const extra = model as unknown as { type: string; serving: boolean }; console.log(`${model.id} type=${extra.type} serving=${extra.serving}`); } ``` Python: ```python import os from hayonix import Client client = Client() openai = client.openai() for model in openai.models.list(): extra = model.model_extra or {} print(f"{model.id} type={extra.get('type')} serving={extra.get('serving')}") ``` Model IDs are publisher/name. In GET /v1/models/{model} the slash may be sent URL-encoded (%2F), as the SDKs do. Without credentials, GET /v1/models lists the public catalog only. ## Billing Requests to shared models are charged per token at the model's prices (pricing on the model). Each request first reserves credit for its worst case and settles at the token counts the engine reports when it ends; an organization without enough credit gets 402 before anything runs. A request cut off by the client is charged for its prompt and the tokens already sent. Requests to a dedicated endpoint are not charged per token; its replicas are billed by the second instead. ## Limits Requests and tokens per minute are limited per organization and model. Every response carries the x-ratelimit-* and ratelimit-* headers described in Limits and quotas; a refused request gets 429 with retry-after. ## Errors Errors use the standard envelope. The ones specific to inference: | Status | code | When | | 400 | malformed_json, invalid_body, invalid_model, invalid_value | The body is not valid JSON, or a field the gateway checks is wrong (param names it) | | 400 | model_not_supported | The model's type does not serve this route (an embedding model on chat completions) | | 400 | engine_rejected | The engine refused the request (for example, a parameter the model does not support) | | 402 | insufficient_credit, spend_limit_reached | Not enough credit to reserve the request | | 404 | model_not_found | No such model, or not visible to your project | | 429 | rate_limited | Over the requests or tokens per minute | | 503 | engine_unavailable, model_unavailable | No replica can take the request right now; retry later | | 504 | timeout, engine_timeout | The model did not answer in time | Every response carries x-request-id; quote it when you report a problem. --- # Speech, transcription and images (OpenAI-compatible) URL: https://hayonix.ai/docs/reference/audio-and-images Text-to-speech, speech-to-text, translation and image generation on the OpenAI-compatible routes, with how each is measured, billed and limited. Speech, audio and image models are called on the same OpenAI-compatible routes and with the same key as chat models, so the official OpenAI SDKs work with only the base URL and key changed: - API_KEY: sk_… (your project API key) - API_BASE_URL: https://api.hayonix.ai/v1 - INFERENCE_BASE_URL: https://api.hayonix.ai/v1 | Method | Path | Model type | What it does | | POST | /v1/audio/speech | text_to_speech | Speech from text, streamed as it is produced | | POST | /v1/audio/transcriptions | speech_to_text | Text from an audio upload, with timings | | POST | /v1/audio/translations | speech_to_text | English text from audio in any language | | POST | /v1/images/generations | image | Images from a prompt | ## Text to speech The body has model, input (up to 4096 characters), voice, and optionally response_format (mp3 by default, or opus, aac, flac, wav, pcm) and speed (0.25–4). The voices a model offers are listed in its capabilities.voices; OpenAI's voice names are accepted where the model has a voice of that name. The answer is the audio itself, sent as it is produced, so playback can start before synthesis ends. pcm is raw 16-bit mono samples at 24 kHz. curl: ```bash jq -n --arg model "$SPEECH_MODEL" '{ model: $model, input: "The quick brown fox jumps over the lazy dog.", voice: "af_heart", response_format: "wav" }' | curl -sS --fail-with-body "$INFERENCE_BASE_URL/audio/speech" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- \ -o speech.wav ``` TypeScript: ```typescript const openai = await client.openai(); const speech = await openai.audio.speech.create({ model: speechModel, input: 'The quick brown fox jumps over the lazy dog.', voice: 'af_heart', response_format: 'wav', }); // The audio streams as it is produced; this saves the whole file. await writeFile(join(dir, 'speech.wav'), Buffer.from(await speech.arrayBuffer())); ``` Python: ```python openai = client.openai() path = os.path.join(workdir, "speech.wav") # The audio streams as it is produced; this writes it to the file as it arrives. with openai.audio.speech.with_streaming_response.create( model=speech_model, input="The quick brown fox jumps over the lazy dog.", voice="af_heart", response_format="wav", ) as response: response.stream_to_file(path) ``` ## Transcription and translation Upload the audio as multipart/form-data (file, up to 25 MB, in any common format) with model, and optionally language (an ISO-639-1 code; detected when omitted), prompt (words or style to expect), temperature and response_format: json (the default), text, srt, vtt or verbose_json. verbose_json adds the language, the duration and timed segments; add timestamp_granularities[]=word for word timings as well. Translations take the same form (without language) and always answer in English. curl: ```bash curl -sS --fail-with-body "$INFERENCE_BASE_URL/audio/transcriptions" \ -H "Authorization: Bearer $API_KEY" \ -F model="$TRANSCRIPTION_MODEL" -F file=@speech.wav \ -F response_format=verbose_json -F 'timestamp_granularities[]=word' | jq -r '"transcript: \(.text)", (.words[] | " \(.start)s \(.word)"), "billed: \(.usage.seconds) s of audio"' ``` TypeScript: ```typescript const transcript = await openai.audio.transcriptions.create({ model: transcriptionModel, file: await toFile(await readFile(join(dir, 'speech.wav')), 'speech.wav'), response_format: 'verbose_json', timestamp_granularities: ['word'], }); console.log(`transcript: ${transcript.text}`); for (const w of transcript.words ?? []) console.log(` ${w.start.toFixed(2)}s ${w.word}`); const seconds = transcript.usage?.type === 'duration' ? transcript.usage.seconds : 0; console.log(`billed: ${String(seconds)} s of audio`); ``` Python: ```python with open(path, "rb") as audio: transcript = openai.audio.transcriptions.create( model=transcription_model, file=audio, response_format="verbose_json", timestamp_granularities=["word"], ) print(f"transcript: {transcript.text}") for w in transcript.words or []: print(f" {w.start:.2f}s {w.word}") print(f"billed: {transcript.usage.seconds if transcript.usage else 0} s of audio") ``` The usage object of a transcription ({"type": "duration", "seconds": …}) is the audio length you are billed for. ## Images The body has model, prompt, and optionally n (1–4), size (WIDTHxHEIGHT, sides of 256–2048 pixels in steps of 64, at most 2 megapixels; auto is the model's default), quality (hd or high run twice the model's standard steps), output_format (png, jpeg, webp) and output_compression. Images come back base64-encoded in data[].b64_json. Image links (response_format: "url") are not offered: such a request is refused with unsupported_parameter. curl: ```bash status=$(jq -n --arg model "$IMAGE_MODEL" '{ model: $model, prompt: "a lighthouse on a cliff at dusk, watercolour", size: "512x512", n: 1 }' | curl -sS "$INFERENCE_BASE_URL/images/generations" \ -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- \ -o image.json -w '%{http_code}') if [ "$status" = 200 ]; then jq -r '.data[0].b64_json' image.json | base64 -d > image.png echo "image: saved image.png" fi ``` TypeScript: ```typescript const image = await openai.images.generate({ model: imageModel, prompt: 'a lighthouse on a cliff at dusk, watercolour', size: '512x512', n: 1, }); const b64 = image.data?.[0]?.b64_json ?? ''; await writeFile(join(dir, 'image.png'), Buffer.from(b64, 'base64')); console.log('image: saved image.png'); ``` Python: ```python image = openai.images.generate( model=image_model, prompt="a lighthouse on a cliff at dusk, watercolour", size="512x512", n=1, ) with open(os.path.join(workdir, "image.png"), "wb") as f: f.write(base64.b64decode(image.data[0].b64_json)) print("image: saved image.png") ``` Image models run on GPU capacity; when none is serving a model, its requests get 503 model_unavailable (the playground shows this as "not being served"). ## Billing Each route bills one measured quantity at the model's price (pricing.units on the model): | Route | Billed per | Measured by | | Speech | Input character (Unicode code point) | The input you send, counted before synthesis | | Transcription, translation | Millisecond of audio (prices are shown per minute) | The length the model decoded from your file | | Images | Image, by size tier (up to 512×512, up to 1024×1024, up to 2 megapixels) | The images returned; an hd image counts twice | Before the model is called, each request reserves credit for its upper bound: the input's characters, the images asked for, or the longest audio the upload could contain (read from a WAV header, otherwise from the file size, at most two hours). An organization without enough credit gets 402 before anything runs. When the request ends, the reservation settles for what was measured and the rest is released. A speech stream you stop early is charged for the characters the delivered audio covers (an estimate, marked as such in usage); an image request you abandon before it answers is not charged. These routes cannot be used in batches, and these models are served on the shared fleet only, not on dedicated endpoints. ## Limits Requests per minute are limited per organization and model as for every model; the second limit counts the route's own unit per minute, reported in headers named after it: x-ratelimit-*-audio-seconds (transcription and translation), x-ratelimit-*-characters (speech) and x-ratelimit-*-images (images). See Limits and quotas. ## Errors Errors use the standard envelope. Beyond the inference errors: | Status | code | When | | 400 | invalid_content_type, invalid_multipart | A transcription that is not a well-formed multipart/form-data upload | | 400 | missing_parameter, invalid_value | A required field is missing or out of range (param names it) | | 400 | unsupported_parameter | A parameter this model cannot honour (streaming transcription, instructions, image url responses, …) | | 400 | route_not_available_for_batch | One of these routes in a batch | | 413 | payload_too_large | An upload over the size limit | --- # API reference URL: https://hayonix.ai/docs/reference --- ## Account ### The signed-in user, memberships, projects and pending invitations URL: https://hayonix.ai/docs/reference/account/get-me GET /v1/me The signed-in user, memberships, projects and pending invitations For a signed-in user only (an API key learns its organization and project from `GET /v1/caller`). Each membership lists the permissions its role grants, for showing or hiding controls. Authentication: Console session only. The console calls this with a signed-in session; API keys are refused. Response: 200 Me Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### The credential making the request, with its org, project and permissions URL: https://hayonix.ai/docs/reference/account/get-caller GET /v1/caller The credential making the request, with its org, project and permissions Answers for any project credential. Clients use it to learn the org an API key belongs to, which org-level routes take in their path. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. TypeScript: client.account.getCaller(…) Python: client.account.get_caller(…) Response: 200 Caller Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/caller" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.account.getCaller(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.account.get_caller() print(result) ``` CLI: ```bash hayonix api account.getCaller ``` --- ## Organizations ### List the organizations you belong to URL: https://hayonix.ai/docs/reference/organizations/list-organizations GET /v1/orgs List the organizations you belong to Returns every organization you are a member of, with your role in each, ordered by ID (oldest first). Only available to a signed-in user, not to API keys. Authentication: Console session only. The console calls this with a signed-in session; API keys are refused. Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Create an organization (you become its owner; a default project is created) URL: https://hayonix.ai/docs/reference/organizations/create-organization POST /v1/orgs Create an organization (you become its owner; a default project is created) Creates the organization with you as its owner, its credit balance and a first project, all at once. The response includes that default project. Organizations cannot be deleted. Authentication: Console session only. The console calls this with a signed-in session; API keys are refused. Request body (JSON): - name (required): Its name - slug: Globally unique; derived from the name when omitted Response: 201 CreatedOrganization Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Get an organization URL: https://hayonix.ai/docs/reference/organizations/get-organization GET /v1/orgs/{org_id} Get an organization Returns the organization with your role in it (`role` is null when the caller is an API key). Authentication: Console session only: no API key can be granted the `org:read` permission it needs. Requires the `org:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Response: 200 Organization Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Update an organization URL: https://hayonix.ai/docs/reference/organizations/update-organization PATCH /v1/orgs/{org_id} Update an organization Changes the name or slug; fields you omit are left as they are. A slug already used by another organization answers 409. Authentication: Console session only: no API key can be granted the `org:update` permission it needs. Requires the `org:update` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - name: Its name - slug: New slug: lowercase letters, digits and hyphens, globally unique (409 `slug_taken` when another organization has it) Response: 200 Organization Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## Members ### List members URL: https://hayonix.ai/docs/reference/members/list-members GET /v1/orgs/{org_id}/members List members Returns the people in the organization with their roles, oldest first. Authentication: Console session only: no API key can be granted the `member:read` permission it needs. Requires the `member:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Get a member URL: https://hayonix.ai/docs/reference/members/get-member GET /v1/orgs/{org_id}/members/{member_id} Get a member Returns one membership: the user and their role in the organization. Authentication: Console session only: no API key can be granted the `member:read` permission it needs. Requires the `member:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - member_id (required): ID of the member Response: 200 Member Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Change a member's role URL: https://hayonix.ai/docs/reference/members/update-member PATCH /v1/orgs/{org_id}/members/{member_id} Change a member's role You can change the role only of a member who ranks no higher than you, and only to a role no higher than your own. The last owner cannot be given another role (409 `last_owner`). Setting the role a member already has changes nothing. Authentication: Console session only: no API key can be granted the `member:update` permission it needs. Requires the `member:update` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - member_id (required): ID of the member Request body (JSON): - role (required) Response: 200 Member Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Remove a member URL: https://hayonix.ai/docs/reference/members/remove-member DELETE /v1/orgs/{org_id}/members/{member_id} Remove a member Takes the user out of the organization; their access ends at once. You can remove only a member who ranks no higher than you, and the last owner cannot be removed (409 `last_owner`). Authentication: Console session only: no API key can be granted the `member:remove` permission it needs. Requires the `member:remove` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - member_id (required): ID of the member Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## Invitations ### List invitations URL: https://hayonix.ai/docs/reference/invitations/list-invitations GET /v1/orgs/{org_id}/invitations List invitations Returns the invitations the organization has sent, newest first, in every state unless you filter by `status`. Authentication: Console session only: no API key can be granted the `member:read` permission it needs. Requires the `member:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - status: Only invitations in this state Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Invite someone by email (a pending invitation to the same address is replaced) URL: https://hayonix.ai/docs/reference/invitations/create-invitation POST /v1/orgs/{org_id}/invitations Invite someone by email (a pending invitation to the same address is replaced) Emails an invitation to join the organization with the given role, which may be no higher than your own. The invitee accepts it while signed in with that verified address, before `expires_at`. Authentication: Console session only: no API key can be granted the `member:invite` permission it needs. Requires the `member:invite` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - email (required): Email address to invite; the invitation is sent there - role (required) Response: 201 Invitation Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Cancel a pending invitation URL: https://hayonix.ai/docs/reference/invitations/cancel-invitation DELETE /v1/orgs/{org_id}/invitations/{invitation_id} Cancel a pending invitation Withdraws a pending invitation so it can no longer be accepted. An invitation that is no longer pending is returned unchanged. Authentication: Console session only: no API key can be granted the `member:invite` permission it needs. Requires the `member:invite` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - invitation_id (required): ID of the invitation Response: 200 Invitation Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Accept an invitation addressed to your verified email URL: https://hayonix.ai/docs/reference/invitations/accept-invitation POST /v1/orgs/{org_id}/invitations/{invitation_id}/accept Accept an invitation addressed to your verified email Makes you a member of the organization with the role the invitation names, and returns the new membership. An invitation addressed to someone else answers 404. Authentication: Console session only. The console calls this with a signed-in session; API keys are refused. Path parameters: - org_id (required): ID of the organization - invitation_id (required): ID of the invitation Response: 200 Member Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## Projects ### List projects URL: https://hayonix.ai/docs/reference/projects/list-projects GET /v1/orgs/{org_id}/projects List projects Returns the organization’s projects, newest first, including archived ones unless you filter with `archived`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `project:read` permission (a key's scope, or a role that includes it). TypeScript: client.projects.list(…) Python: client.projects.list(…) Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - archived: Filter by archived state Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/projects" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.projects.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.projects.list(): print(item) ``` CLI: ```bash hayonix api projects.list ``` ### Create a project URL: https://hayonix.ai/docs/reference/projects/create-project POST /v1/orgs/{org_id}/projects Create a project Creates a project in the organization. When `slug` is omitted it is derived from the name; a slug already used in this organization answers 409. Authentication: Console session only: no API key can be granted the `project:create` permission it needs. Requires the `project:create` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - name (required): Its name - slug: Defaults to one derived from the name - description: Free-text description Response: 201 Project Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Get a project URL: https://hayonix.ai/docs/reference/projects/get-project GET /v1/orgs/{org_id}/projects/{project_id} Get a project Returns one project, archived or not. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `project:read` permission (a key's scope, or a role that includes it). TypeScript: client.projects.get(…) Python: client.projects.get(…) Path parameters: - org_id (required): ID of the organization - project_id (required): ID of the project Response: 200 Project Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/projects/prj_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const project = await client.projects.get('prj_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(project); ``` Python: ```python from hayonix import Client client = Client() project = client.projects.get("prj_01jc5zq4m8k3v6x9t2w7r0b1e4") print(project) ``` CLI: ```bash hayonix api projects.get prj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Update a project URL: https://hayonix.ai/docs/reference/projects/update-project PATCH /v1/orgs/{org_id}/projects/{project_id} Update a project Changes the name, slug or description; fields you omit are left as they are. A slug already used in this organization answers 409. Authentication: Console session only: no API key can be granted the `project:update` permission it needs. Requires the `project:update` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - project_id (required): ID of the project Request body (JSON): - name: Its name - slug: New slug: lowercase letters, digits and hyphens, unique within the organization (409 `slug_taken` otherwise) - description: Free-text description Response: 200 Project Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Archive a project (projects are never deleted) URL: https://hayonix.ai/docs/reference/projects/archive-project POST /v1/orgs/{org_id}/projects/{project_id}/archive Archive a project (projects are never deleted) Makes the project read-only: its resources can still be read, but any change inside it answers 409 `project_archived` until it is restored. Archiving an archived project returns it unchanged. Authentication: Console session only: no API key can be granted the `project:delete` permission it needs. Requires the `project:delete` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - project_id (required): ID of the project Response: 200 Project Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Restore an archived project URL: https://hayonix.ai/docs/reference/projects/unarchive-project POST /v1/orgs/{org_id}/projects/{project_id}/unarchive Restore an archived project Makes an archived project writable again. Restoring a project that is not archived returns it unchanged. Authentication: Console session only: no API key can be granted the `project:update` permission it needs. Requires the `project:update` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - project_id (required): ID of the project Response: 200 Project Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## API keys ### List API keys in the project URL: https://hayonix.ai/docs/reference/api-keys/list-api-keys GET /v1/api-keys List API keys in the project Returns the project’s keys, newest first, including revoked and expired ones. Secrets are never included. Authentication: Console session only: no API key can be granted the `api_key:read` permission it needs. Requires the `api_key:read` permission (a key's scope, or a role that includes it). Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Create an API key (the secret is returned once) URL: https://hayonix.ai/docs/reference/api-keys/create-api-key POST /v1/api-keys Create an API key (the secret is returned once) Creates a key that acts inside this project with the scopes you give it, which may not exceed what your own role grants. The secret appears only in this response and cannot be read again; a replay with the same `Idempotency-Key` returns the same response. Authentication: Console session only: no API key can be granted the `api_key:create` permission it needs. Requires the `api_key:create` permission (a key's scope, or a role that includes it). Request body (JSON): - name (required): Its name - scopes (required): Actions (`resource:verb`) or `resource:*`; at most your own role grants - expires_at: When it expires (null: never) (ISO 8601, UTC) Response: 201 CreatedApiKey Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Get an API key URL: https://hayonix.ai/docs/reference/api-keys/get-api-key GET /v1/api-keys/{api_key_id} Get an API key Returns one key’s details and status; the secret is never included. Authentication: Console session only: no API key can be granted the `api_key:read` permission it needs. Requires the `api_key:read` permission (a key's scope, or a role that includes it). Path parameters: - api_key_id (required): ID of the api key Response: 200 ApiKey Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Rename an API key URL: https://hayonix.ai/docs/reference/api-keys/update-api-key PATCH /v1/api-keys/{api_key_id} Rename an API key Changes only the name; the secret, scopes and expiry stay as they are. Authentication: Console session only: no API key can be granted the `api_key:update` permission it needs. Requires the `api_key:update` permission (a key's scope, or a role that includes it). Path parameters: - api_key_id (required): ID of the api key Request body (JSON): - name (required): Its name Response: 200 ApiKey Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Revoke an API key (takes effect immediately; idempotent) URL: https://hayonix.ai/docs/reference/api-keys/revoke-api-key POST /v1/api-keys/{api_key_id}/revoke Revoke an API key (takes effect immediately; idempotent) Every later request made with the key is refused. Revoking a key that is already revoked returns it unchanged. Authentication: Console session only: no API key can be granted the `api_key:delete` permission it needs. Requires the `api_key:delete` permission (a key's scope, or a role that includes it). Path parameters: - api_key_id (required): ID of the api key Response: 200 ApiKey Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## SSH keys ### List SSH keys URL: https://hayonix.ai/docs/reference/ssh-keys/list-ssh-keys GET /v1/ssh-keys List SSH keys The project’s SSH public keys, newest first. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `ssh_key:read` permission (a key's scope, or a role that includes it). TypeScript: client.sshKeys.list(…) Python: client.ssh_keys.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/ssh-keys" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.sshKeys.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.ssh_keys.list(): print(item) ``` CLI: ```bash hayonix api sshKeys.list ``` ### Add an SSH public key URL: https://hayonix.ai/docs/reference/ssh-keys/create-ssh-key POST /v1/ssh-keys Add an SSH public key Adds a public key to the project. Pods of the project with SSH on accept it within moments, without restarting any container. Adding a key that is already in the project is a conflict. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `ssh_key:create` permission (a key's scope, or a role that includes it). TypeScript: client.sshKeys.create(…) Python: client.ssh_keys.create(…) Request body (JSON): - name: Defaults to the key's comment - public_key (required): One OpenSSH public key line Response: 201 SshKey Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/ssh-keys" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHZG+FGe8of8lnaS3zftZ6bPg69OKrEd9xvDOWK5wqx0 laptop" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const key = await client.sshKeys.create({ name: 'laptop', public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHZG+FGe8of8lnaS3zftZ6bPg69OKrEd9xvDOWK5wqx0 laptop', }); console.log(key); ``` Python: ```python from hayonix import Client client = Client() key = client.ssh_keys.create( name="laptop", public_key="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHZG+FGe8of8lnaS3zftZ6bPg69OKrEd9xvDOWK5wqx0 laptop", ) print(key) ``` CLI: ```bash hayonix api sshKeys.create \ --body '{"name":"laptop","public_key":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHZG+FGe8of8lnaS3zftZ6bPg69OKrEd9xvDOWK5wqx0 laptop"}' ``` ### Get an SSH key URL: https://hayonix.ai/docs/reference/ssh-keys/get-ssh-key GET /v1/ssh-keys/{ssh_key_id} Get an SSH key Returns one key with its public part and fingerprint. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `ssh_key:read` permission (a key's scope, or a role that includes it). TypeScript: client.sshKeys.get(…) Python: client.ssh_keys.get(…) Path parameters: - ssh_key_id (required): ID of the ssh key Response: 200 SshKey Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/ssh-keys/ssh_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const key = await client.sshKeys.get('ssh_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(key); ``` Python: ```python from hayonix import Client client = Client() key = client.ssh_keys.get("ssh_01jc5zq4m8k3v6x9t2w7r0b1e4") print(key) ``` CLI: ```bash hayonix api sshKeys.get ssh_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Rename an SSH key URL: https://hayonix.ai/docs/reference/ssh-keys/update-ssh-key PATCH /v1/ssh-keys/{ssh_key_id} Rename an SSH key Changes the key’s name only; the key itself cannot be changed (add a new one). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `ssh_key:update` permission (a key's scope, or a role that includes it). TypeScript: client.sshKeys.update(…) Python: client.ssh_keys.update(…) Path parameters: - ssh_key_id (required): ID of the ssh key Request body (JSON): - name (required): Its name Response: 200 SshKey Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/ssh-keys/ssh_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "work laptop" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const key = await client.sshKeys.update('ssh_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'work laptop' }); console.log(key); ``` Python: ```python from hayonix import Client client = Client() key = client.ssh_keys.update("ssh_01jc5zq4m8k3v6x9t2w7r0b1e4", name="work laptop") print(key) ``` CLI: ```bash hayonix api sshKeys.update ssh_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"name":"work laptop"}' ``` ### Delete an SSH key URL: https://hayonix.ai/docs/reference/ssh-keys/delete-ssh-key DELETE /v1/ssh-keys/{ssh_key_id} Delete an SSH key Removes the key from the project. Within moments pods stop accepting it, and open SSH sessions made with it are closed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `ssh_key:delete` permission (a key's scope, or a role that includes it). TypeScript: client.sshKeys.delete(…) Python: client.ssh_keys.delete(…) Path parameters: - ssh_key_id (required): ID of the ssh key Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/ssh-keys/ssh_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const key = await client.sshKeys.delete('ssh_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(key); ``` Python: ```python from hayonix import Client client = Client() key = client.ssh_keys.delete("ssh_01jc5zq4m8k3v6x9t2w7r0b1e4") print(key) ``` CLI: ```bash hayonix api sshKeys.delete ssh_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Secrets ### List secrets URL: https://hayonix.ai/docs/reference/secrets/list-secrets GET /v1/secrets List secrets The project’s secrets, newest first: names and dates only, never values. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `secret:read` permission (a key's scope, or a role that includes it). TypeScript: client.secrets.list(…) Python: client.secrets.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/secrets" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.secrets.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.secrets.list(): print(item) ``` CLI: ```bash hayonix api secrets.list ``` ### Create a secret URL: https://hayonix.ai/docs/reference/secrets/create-secret POST /v1/secrets Create a secret Stores a value encrypted under a name unique in the project. Workloads reference it by ID (pods through `secret_env`); no route ever returns the value. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `secret:create` permission (a key's scope, or a role that includes it). TypeScript: client.secrets.create(…) Python: client.secrets.create(…) Request body (JSON): - name (required): Environment-variable style name, unique in the project - value (required): Write-only. Never returned. Response: 201 Secret Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/secrets" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "HF_TOKEN", "value": "hf_example_value" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const secret = await client.secrets.create({ name: 'HF_TOKEN', value: 'hf_example_value' }); console.log(secret); ``` Python: ```python from hayonix import Client client = Client() secret = client.secrets.create(name="HF_TOKEN", value="hf_example_value") print(secret) ``` CLI: ```bash hayonix api secrets.create --body '{"name":"HF_TOKEN","value":"hf_example_value"}' ``` ### Get a secret (metadata only) URL: https://hayonix.ai/docs/reference/secrets/get-secret GET /v1/secrets/{secret_id} Get a secret (metadata only) Returns the secret’s name and dates; the value is never returned. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `secret:read` permission (a key's scope, or a role that includes it). TypeScript: client.secrets.get(…) Python: client.secrets.get(…) Path parameters: - secret_id (required): ID of the secret Response: 200 Secret Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/secrets/sec_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const secret = await client.secrets.get('sec_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(secret); ``` Python: ```python from hayonix import Client client = Client() secret = client.secrets.get("sec_01jc5zq4m8k3v6x9t2w7r0b1e4") print(secret) ``` CLI: ```bash hayonix api secrets.get sec_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Rename a secret or replace its value URL: https://hayonix.ai/docs/reference/secrets/update-secret PATCH /v1/secrets/{secret_id} Rename a secret or replace its value Changes the name, the value or both. Containers already running keep the value they started with; containers created afterwards get the new one. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `secret:update` permission (a key's scope, or a role that includes it). TypeScript: client.secrets.update(…) Python: client.secrets.update(…) Path parameters: - secret_id (required): ID of the secret Request body (JSON): - name: Environment-variable style name, unique in the project - value: Write-only. Never returned. Response: 200 Secret Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/secrets/sec_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": "hf_rotated_value" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const secret = await client.secrets.update('sec_01jc5zq4m8k3v6x9t2w7r0b1e4', { value: 'hf_rotated_value' }); console.log(secret); ``` Python: ```python from hayonix import Client client = Client() secret = client.secrets.update( "sec_01jc5zq4m8k3v6x9t2w7r0b1e4", value="hf_rotated_value", ) print(secret) ``` CLI: ```bash hayonix api secrets.update \ sec_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"value":"hf_rotated_value"}' ``` ### Delete a secret URL: https://hayonix.ai/docs/reference/secrets/delete-secret DELETE /v1/secrets/{secret_id} Delete a secret Deletes the secret and its value. Running containers keep their environment, but a workload that still references it cannot start a new container until the reference is removed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `secret:delete` permission (a key's scope, or a role that includes it). TypeScript: client.secrets.delete(…) Python: client.secrets.delete(…) Path parameters: - secret_id (required): ID of the secret Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/secrets/sec_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const secret = await client.secrets.delete('sec_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(secret); ``` Python: ```python from hayonix import Client client = Client() secret = client.secrets.delete("sec_01jc5zq4m8k3v6x9t2w7r0b1e4") print(secret) ``` CLI: ```bash hayonix api secrets.delete sec_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Registry credentials ### List registry credentials URL: https://hayonix.ai/docs/reference/registry-credentials/list-registry-credentials GET /v1/registry-credentials List registry credentials The project’s registry credentials, newest first, without passwords. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `registry_credential:read` permission (a key's scope, or a role that includes it). TypeScript: client.registryCredentials.list(…) Python: client.registry_credentials.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/registry-credentials" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.registryCredentials.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.registry_credentials.list(): print(item) ``` CLI: ```bash hayonix api registryCredentials.list ``` ### Add registry credentials URL: https://hayonix.ai/docs/reference/registry-credentials/create-registry-credential POST /v1/registry-credentials Add registry credentials Stores sign-in details for one private container registry, with a name unique in the project; the password is encrypted and never returned. Pods and private templates use them through `registry_credential_id` to pull private images. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `registry_credential:create` permission (a key's scope, or a role that includes it). TypeScript: client.registryCredentials.create(…) Python: client.registry_credentials.create(…) Request body (JSON): - name (required): Its name - registry (required): Registry host and optional port, no scheme - username (required): User name to sign in to the registry with - password (required): Password or access token. Write-only. Response: 201 RegistryCredential Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/registry-credentials" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "ghcr", "registry": "ghcr.io", "username": "deploy-bot", "password": "ghp_example" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const credential = await client.registryCredentials.create({ name: 'ghcr', registry: 'ghcr.io', username: 'deploy-bot', password: 'ghp_example', }); console.log(credential); ``` Python: ```python from hayonix import Client client = Client() credential = client.registry_credentials.create( name="ghcr", registry="ghcr.io", username="deploy-bot", password="ghp_example", ) print(credential) ``` CLI: ```bash hayonix api registryCredentials.create \ --body '{"name":"ghcr","registry":"ghcr.io","username":"deploy-bot","password":"ghp_example"}' ``` ### Get registry credentials (without the password) URL: https://hayonix.ai/docs/reference/registry-credentials/get-registry-credential GET /v1/registry-credentials/{registry_credential_id} Get registry credentials (without the password) Returns the name, registry and user name; the password is never returned. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `registry_credential:read` permission (a key's scope, or a role that includes it). TypeScript: client.registryCredentials.get(…) Python: client.registry_credentials.get(…) Path parameters: - registry_credential_id (required): ID of the registry credential Response: 200 RegistryCredential Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/registry-credentials/rcr_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const credential = await client.registryCredentials.get('rcr_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(credential); ``` Python: ```python from hayonix import Client client = Client() credential = client.registry_credentials.get("rcr_01jc5zq4m8k3v6x9t2w7r0b1e4") print(credential) ``` CLI: ```bash hayonix api registryCredentials.get rcr_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Update registry credentials URL: https://hayonix.ai/docs/reference/registry-credentials/update-registry-credential PATCH /v1/registry-credentials/{registry_credential_id} Update registry credentials Changes only the fields sent, for example to rotate the password. Containers already created are not affected; the new details are used the next time a container is created. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `registry_credential:update` permission (a key's scope, or a role that includes it). TypeScript: client.registryCredentials.update(…) Python: client.registry_credentials.update(…) Path parameters: - registry_credential_id (required): ID of the registry credential Request body (JSON): - name: Its name - registry: Registry host and optional port, no scheme - username: User name to sign in to the registry with - password: Password or access token. Write-only. Response: 200 RegistryCredential Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/registry-credentials/rcr_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "password": "ghp_rotated" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const credential = await client.registryCredentials.update('rcr_01jc5zq4m8k3v6x9t2w7r0b1e4', { password: 'ghp_rotated' }); console.log(credential); ``` Python: ```python from hayonix import Client client = Client() credential = client.registry_credentials.update( "rcr_01jc5zq4m8k3v6x9t2w7r0b1e4", password="ghp_rotated", ) print(credential) ``` CLI: ```bash hayonix api registryCredentials.update \ rcr_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"password":"ghp_rotated"}' ``` ### Delete registry credentials URL: https://hayonix.ai/docs/reference/registry-credentials/delete-registry-credential DELETE /v1/registry-credentials/{registry_credential_id} Delete registry credentials Deletes the credentials and their password. Running containers are not affected, but a workload that still references them cannot start a new container until the reference is changed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `registry_credential:delete` permission (a key's scope, or a role that includes it). TypeScript: client.registryCredentials.delete(…) Python: client.registry_credentials.delete(…) Path parameters: - registry_credential_id (required): ID of the registry credential Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/registry-credentials/rcr_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const credential = await client.registryCredentials.delete('rcr_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(credential); ``` Python: ```python from hayonix import Client client = Client() credential = client.registry_credentials.delete("rcr_01jc5zq4m8k3v6x9t2w7r0b1e4") print(credential) ``` CLI: ```bash hayonix api registryCredentials.delete rcr_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Audit logs ### List audit log entries URL: https://hayonix.ai/docs/reference/audit-logs/list-audit-logs GET /v1/orgs/{org_id}/audit-logs List audit log entries Newest first. Entries are kept for the life of the organization and cannot be changed or deleted. Authentication: Console session only: no API key can be granted the `audit_log:read` permission it needs. Requires the `audit_log:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - actor_kind: Only this kind of actor - actor_id: Only this actor: a user ID, an API key ID, a component, or `platform` for platform operators - action: An action (`api_key:create`) or every action on a resource (`api_key:*`) - target_type: Only entries about this kind of resource - target_id: Only entries about this resource - created_after: Entries at or after this time - created_before: Entries before this time Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Export audit log entries as CSV URL: https://hayonix.ai/docs/reference/audit-logs/export-audit-logs GET /v1/orgs/{org_id}/audit-logs/export Export audit log entries as CSV The entries the same filters select in the list, newest first, as one CSV file streamed until the filters are exhausted (no row cap: narrow large exports with a time range). Operator entries are masked as in the list. Authentication: Console session only: no API key can be granted the `audit_log:read` permission it needs. Requires the `audit_log:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Query parameters: - actor_kind: Only this kind of actor - actor_id: Only this actor: a user ID, an API key ID, a component, or `platform` for platform operators - action: An action (`api_key:create`) or every action on a resource (`api_key:*`) - target_type: Only entries about this kind of resource - target_id: Only entries about this resource - created_after: Entries at or after this time - created_before: Entries before this time - cursor: Start after this entry (`next_cursor` of a list page) Response: 200 text (text/csv) Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Get an audit log entry URL: https://hayonix.ai/docs/reference/audit-logs/get-audit-log GET /v1/orgs/{org_id}/audit-logs/{audit_log_id} Get an audit log entry Returns one entry with the request that made the change. Changes made by platform operators show the actor as "Platform operator", without their identity, address or reason. Authentication: Console session only: no API key can be granted the `audit_log:read` permission it needs. Requires the `audit_log:read` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - audit_log_id (required): ID of the audit log Response: 200 AuditLogEntry Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## Billing ### Get the credit balance URL: https://hayonix.ai/docs/reference/billing/get-balance GET /v1/orgs/{org_id}/billing/balance Get the credit balance Returns paid and promotional credit, the amount reserved by work in progress, and what is available for new work. Recent inference spending can take up to about 30 seconds to appear. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.getBalance(…) Python: client.billing.get_balance(…) Path parameters: - org_id (required): ID of the organization Response: 200 Balance Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/balance" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.billing.getBalance(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.billing.get_balance() print(result) ``` CLI: ```bash hayonix api billing.getBalance ``` ### Billing settings, credit standing, spend limits, auto-recharge and limits URL: https://hayonix.ai/docs/reference/billing/get-billing-account GET /v1/orgs/{org_id}/billing/account Billing settings, credit standing, spend limits, auto-recharge and limits Everything that decides whether the organization may spend: balance, suspension, out-of-credit and compute-stop state, spend limits and spend so far, auto-recharge settings, top-up limits and quotas. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.getAccount(…) Python: client.billing.get_account(…) Path parameters: - org_id (required): ID of the organization Response: 200 BillingAccount Errors: - 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. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/account" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.billing.getAccount(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.billing.get_account() print(result) ``` CLI: ```bash hayonix api billing.getAccount ``` ### Set the low-balance alert threshold and spend limits (null clears) URL: https://hayonix.ai/docs/reference/billing/update-billing-account PATCH /v1/orgs/{org_id}/billing/account Set the low-balance alert threshold and spend limits (null clears) Fields you omit are left as they are. A null spend limit removes it; a null threshold restores the default. Changing the threshold re-arms the low-balance email. Reaching a spend limit stops running compute (volumes are kept) and refuses new work until spend falls below it or it is raised. Authentication: Console session only: no API key can be granted the `billing:manage` permission it needs. Requires the `billing:manage` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - low_balance_threshold: Integer nano-USD as a decimal string - hourly_spend_limit: Positive integer nano-USD as a decimal string - monthly_spend_limit: Positive integer nano-USD as a decimal string Response: 200 BillingAccount Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### The rate-limit level: per-minute limits in force and what reaches the next level URL: https://hayonix.ai/docs/reference/billing/get-rate-level GET /v1/orgs/{org_id}/billing/rate-level The rate-limit level: per-minute limits in force and what reaches the next level Inference and batch requests and tokens per minute (per model) come from the organization’s level. A level is reached by credit paid and kept and by account age, both at once; it rises by itself (right after a payment, and as the account ages) and never goes down by itself. A limit set for this organization by the platform wins over its level. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.getRateLevel(…) Python: client.billing.get_rate_level(…) Path parameters: - org_id (required): ID of the organization Response: 200 RateLevel Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/rate-level" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.billing.getRateLevel(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.billing.get_rate_level() print(result) ``` CLI: ```bash hayonix api billing.getRateLevel ``` ### Turn auto-recharge on or off (threshold → target, monthly cap, saved card) URL: https://hayonix.ai/docs/reference/billing/update-auto-recharge PATCH /v1/orgs/{org_id}/billing/auto-recharge Turn auto-recharge on or off (threshold → target, monthly cap, saved card) When enabled, the saved card is charged whenever available credit falls below `threshold`, bringing it back to `target`, never more than `monthly_cap` in a calendar month. Omitted fields keep their previous values; enabling needs a threshold, a target and an active saved card, amounts in whole cents. A suspended account cannot enable it. Authentication: Console session only: no API key can be granted the `billing:manage` permission it needs. Requires the `billing:manage` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - enabled (required): true turns auto-recharge on with the settings below; false turns it off - threshold: Integer nano-USD as a decimal string - target: Positive integer nano-USD as a decimal string - monthly_cap: Positive integer nano-USD as a decimal string - payment_method_id: ID of the payment method Response: 200 BillingAccount Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Start a top-up: returns a payment with the checkout URL to send the customer to URL: https://hayonix.ai/docs/reference/billing/create-top-up POST /v1/orgs/{org_id}/billing/top-ups Start a top-up: returns a payment with the checkout URL to send the customer to Credit is added only when the payment processor confirms the payment (webhook), never by the return page. With the development driver, credit is added at once and the payment is marked `development`. Authentication: Console session only: no API key can be granted the `billing:manage` permission it needs. Requires the `billing:manage` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - amount (required): Credit to buy, nano-USD; a whole number of cents - save_payment_method: Save the card for auto-recharge Response: 201 Payment Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Payment history (top-ups and auto-recharges) with receipt links URL: https://hayonix.ai/docs/reference/billing/list-payments GET /v1/orgs/{org_id}/billing/payments Payment history (top-ups and auto-recharges) with receipt links Returns every payment in any state, newest first. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.listPayments(…) Python: client.billing.list_payments(…) Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/payments" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.billing.listPayments()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.billing.list_payments(): print(item) ``` CLI: ```bash hayonix api billing.listPayments ``` ### Get a payment (the console polls this after Checkout) URL: https://hayonix.ai/docs/reference/billing/get-payment GET /v1/orgs/{org_id}/billing/payments/{payment_id} Get a payment (the console polls this after Checkout) Returns one payment. After the customer pays, poll this until `status` leaves `pending`: credit is added when the payment processor confirms the payment, not when the customer returns from the checkout page. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.getPayment(…) Python: client.billing.get_payment(…) Path parameters: - org_id (required): ID of the organization - payment_id (required): ID of the payment Response: 200 Payment Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/payments/pay_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.billing.getPayment('pay_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.billing.get_payment("pay_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api billing.getPayment pay_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Saved cards URL: https://hayonix.ai/docs/reference/billing/list-payment-methods GET /v1/orgs/{org_id}/billing/payment-methods Saved cards Returns the organization’s active saved cards; removed cards are not listed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.listPaymentMethods(…) Python: client.billing.list_payment_methods(…) Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/payment-methods" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.billing.listPaymentMethods()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.billing.list_payment_methods(): print(item) ``` CLI: ```bash hayonix api billing.listPaymentMethods ``` ### Remove a saved card (turns off auto-recharge if it used this card) URL: https://hayonix.ai/docs/reference/billing/detach-payment-method POST /v1/orgs/{org_id}/billing/payment-methods/{payment_method_id}/detach Remove a saved card (turns off auto-recharge if it used this card) The card is removed from the payment processor and never charged again. Removing a card that is already removed returns it unchanged. Authentication: Console session only: no API key can be granted the `billing:manage` permission it needs. Requires the `billing:manage` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization - payment_method_id (required): ID of the payment method Response: 200 PaymentMethod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Redeem a promo code for promotional credit URL: https://hayonix.ai/docs/reference/billing/redeem-promo-code POST /v1/orgs/{org_id}/billing/promo-redemptions Redeem a promo code for promotional credit Adds the code’s promotional credit, which expires at `expires_at`. Each organization can redeem a code once (409 `already_redeemed`); an unknown or used-up code answers 400. Authentication: Console session only: no API key can be granted the `billing:manage` permission it needs. Requires the `billing:manage` permission (a key's scope, or a role that includes it). Path parameters: - org_id (required): ID of the organization Request body (JSON): - code (required): Machine-readable code Response: 201 PromoRedemption Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. ### Billing emails sent to the organization (low balance, out of credit, payments …) URL: https://hayonix.ai/docs/reference/billing/list-billing-notices GET /v1/orgs/{org_id}/billing/notices Billing emails sent to the organization (low balance, out of credit, payments …) Returns the billing notices written for the organization, newest first, including ones not yet emailed (`sent_at` null). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `billing:read` permission (a key's scope, or a role that includes it). TypeScript: client.billing.listNotices(…) Python: client.billing.list_notices(…) Path parameters: - org_id (required): ID of the organization Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/notices" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.billing.listNotices()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.billing.list_notices(): print(item) ``` CLI: ```bash hayonix api billing.listNotices ``` --- ## Pricing ### Current public prices (no authentication) URL: https://hayonix.ai/docs/reference/pricing/get-price-sheet GET /v1/pricing Current public prices (no authentication) The prices charged from now on, for every product. A new price list is charged from the moment it takes effect, and responses may be cached for up to 30 seconds. Authentication: None: this operation is public. TypeScript: client.pricing.getPriceSheet(…) Python: client.pricing.get_price_sheet(…) Response: 200 PriceSheet Errors: - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pricing" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.pricing.getPriceSheet(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.pricing.get_price_sheet() print(result) ``` CLI: ```bash hayonix api pricing.getPriceSheet ``` --- ## Pods ### Hardware for pods: per SKU, its prices and what can be launched now in each region URL: https://hayonix.ai/docs/reference/pods/list-pod-hardware GET /v1/pods/hardware Hardware for pods: per SKU, its prices and what can be launched now in each region Every active SKU with its hourly prices and, per region, how many units an on-demand or interruptible pod could get right now. The counts are a snapshot; nothing is held for you. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.listHardware(…) Python: client.pods.list_hardware(…) Query parameters: - region: Only this region (default: every active region) Response: 200 JSON Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/hardware" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.listHardware(); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.list_hardware() print(pod) ``` CLI: ```bash hayonix api pods.listHardware ``` ### Price estimate for a pod configuration: hourly running and stopped cost URL: https://hayonix.ai/docs/reference/pods/estimate-pod GET /v1/pods/estimate Price estimate for a pod configuration: hourly running and stopped cost Prices a configuration from the price book in force without creating anything. Network volumes are itemised but kept out of the running and stopped totals, because they are billed whether or not a pod uses them. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.estimate(…) Python: client.pods.estimate(…) Query parameters: - sku (required): SKU code, as listed by the pod hardware route - gpu_count: Number of GPUs: at least 1 for a GPU SKU, 0 for a CPU SKU - pricing_class: `interruptible` costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue to run again. On-demand pods are never preempted. - container_disk_gb: Container disk size in GB - volume_gb: Size of the pod’s own volume in GB (0: none) - network_volume_ids: Comma-separated network volume IDs the pod would mount Response: 200 PodEstimate Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/estimate?sku=gpu-l4-24gb" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.estimate({ sku: 'gpu-l4-24gb' }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.estimate(sku="gpu-l4-24gb") print(pod) ``` CLI: ```bash hayonix api pods.estimate --param sku='gpu-l4-24gb' ``` ### List pods in the project (terminated pods are left out unless asked for) URL: https://hayonix.ai/docs/reference/pods/list-pods GET /v1/pods List pods in the project (terminated pods are left out unless asked for) Pods of the project, newest first. `connect` is null in lists; read one pod for its URLs and SSH details. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.list(…) Python: client.pods.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - include_terminated: Include terminated pods (default false) Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.pods.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.pods.list(): print(item) ``` CLI: ```bash hayonix api pods.list ``` ### Create a pod from a template or an image (launch gate and quotas apply) URL: https://hayonix.ai/docs/reference/pods/create-pod POST /v1/pods Create a pod from a template or an image (launch gate and quotas apply) Creates the pod and queues it; it starts once capacity is free in the region (on the host its volumes are pinned to, if any). With `template_id`, fields left out come from the template. Refused when the organization may not launch (out of credit, suspended) or a quota is reached. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:create` permission (a key's scope, or a role that includes it). TypeScript: client.pods.create(…) Python: client.pods.create(…) Request body (JSON): - name (required): Its name - hostname: Name in the project’s private network (default: from the name) - template_id: ID of the template - image: Image reference; defaults to the template’s - hardware (required) - region (required): Region code - pricing_class: `interruptible` costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue to run again. On-demand pods are never preempted. - container_disk_gb: Writable container disk; reset whenever the container is recreated (stop, reconfigure). Default 20. - network_volumes: Network volumes to mount. A pod that mounts a volume runs on the host the volume is pinned to. - ports: Container ports to expose; each public HTTP port gets its own HTTPS URL - env: Plain environment variables. Names starting with POD_, NVIDIA_ or LD_ are reserved. - secret_env: Environment variables whose values come from project secrets, read when the container is created. - command: Replaces the image’s entrypoint when non-empty - args: Replaces the image’s default arguments when non-empty - registry_credential_id: ID of the registry credential - ssh: Allow SSH (and SFTP, port forwarding) with the project’s SSH keys - models: Models from the model hub, cached on the host and mounted read-only at /model-cache/models---- (HF_HUB_CACHE points there unless env sets it). Changing them recreates the container. - volume: The pod’s own persistent volume (default: the template’s; null for none). It survives stops and reconfiguration and is deleted on terminate unless kept. Response: 201 Pod Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "notebook", "image": "quay.io/jupyter/base-notebook:2026-11-10", "hardware": { "sku": "cpu-2c-4gb", "gpu_count": 0 }, "region": "dev-local-1", "volume": { "size_gb": 10, "mount_path": "/home/jovyan/work" }, "ports": [ { "port": 8888, "protocol": "http", "visibility": "public" } ] }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.create({ name: 'notebook', image: 'quay.io/jupyter/base-notebook:2026-11-10', hardware: { sku: 'cpu-2c-4gb', gpu_count: 0 }, region: 'dev-local-1', volume: { size_gb: 10, mount_path: '/home/jovyan/work' }, ports: [{ port: 8888, protocol: 'http', visibility: 'public' }], }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.create( name="notebook", image="quay.io/jupyter/base-notebook:2026-11-10", hardware={"sku": "cpu-2c-4gb", "gpu_count": 0}, region="dev-local-1", volume={"size_gb": 10, "mount_path": "/home/jovyan/work"}, ports=[{"port": 8888, "protocol": "http", "visibility": "public"}], ) print(pod) ``` CLI: ```bash hayonix api pods.create \ --body '{"name":"notebook","image":"quay.io/jupyter/base-notebook:2026-11-10","hardware":{"sku":"cpu-2c-4gb","gpu_count":0},"region":"dev-local-1","volume":{"size_gb":10,"mount_path":"/home/jovyan/work"},"ports":[{"port":8888,"protocol":"http","visibility":"public"}]}' ``` ### Get a pod: its state, configuration and how to connect URL: https://hayonix.ai/docs/reference/pods/get-pod GET /v1/pods/{pod_id} Get a pod: its state, configuration and how to connect Returns the pod with its current state, configuration, volumes and connection details (port URLs, SSH and private-network name). A terminated pod stays readable, without connection details. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.get(…) Python: client.pods.get(…) Path parameters: - pod_id (required): ID of the pod Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.get('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.get("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.get pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Rename a pod (does not touch the container) URL: https://hayonix.ai/docs/reference/pods/rename-pod PATCH /v1/pods/{pod_id} Rename a pod (does not touch the container) Changes the display name only; the private-network hostname, configuration and container stay as they are. Refused for a terminated pod. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.rename(…) Python: client.pods.rename(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - name (required): Its name Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "trainer" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.rename('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'trainer' }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.rename("pod_01jc5zq4m8k3v6x9t2w7r0b1e4", name="trainer") print(pod) ``` CLI: ```bash hayonix api pods.rename pod_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"name":"trainer"}' ``` ### Change a pod’s configuration (recreates the container; only volume data survives) URL: https://hayonix.ai/docs/reference/pods/reconfigure-pod POST /v1/pods/{pod_id}/reconfigure Change a pod’s configuration (recreates the container; only volume data survives) Applies a new configuration revision: the container is recreated and everything outside volumes is lost. Changing hardware, region, pricing class or volumes also moves the pod off its host and queues it again. With `dry_run` nothing changes; a request that changes nothing applies nothing. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.reconfigure(…) Python: client.pods.reconfigure(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - image: Image reference; defaults to the template’s - hardware - region: Region code - pricing_class: `interruptible` costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue to run again. On-demand pods are never preempted. - container_disk_gb: Writable container disk; reset whenever the container is recreated (stop, reconfigure). Default 20. - network_volumes: Network volumes to mount. A pod that mounts a volume runs on the host the volume is pinned to. - ports: Container ports to expose; each public HTTP port gets its own HTTPS URL - env: Plain environment variables. Names starting with POD_, NVIDIA_ or LD_ are reserved. - secret_env: Environment variables whose values come from project secrets, read when the container is created. - command: Replaces the image’s entrypoint when non-empty - args: Replaces the image’s default arguments when non-empty - registry_credential_id: ID of the registry credential - ssh: Allow SSH (and SFTP, port forwarding) with the project’s SSH keys - models: Models from the model hub, cached on the host and mounted read-only at /model-cache/models---- (HF_HUB_CACHE points there unless env sets it). Changing them recreates the container. - volume: Swap or detach (null) the pod volume - dry_run: Only report what would change (nothing is applied) Response: 200 PodReconfiguration Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/reconfigure" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "env": [ { "name": "MODE", "value": "debug" } ], "dry_run": true }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.reconfigure('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { env: [{ name: 'MODE', value: 'debug' }], dry_run: true }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.reconfigure( "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", env=[{"name": "MODE", "value": "debug"}], dry_run=True, ) print(pod) ``` CLI: ```bash hayonix api pods.reconfigure \ pod_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"env":[{"name":"MODE","value":"debug"}],"dry_run":true}' ``` ### Start a stopped pod (placed again; on its volume’s host if it has one) URL: https://hayonix.ai/docs/reference/pods/start-pod POST /v1/pods/{pod_id}/start Start a stopped pod (placed again; on its volume’s host if it has one) Asks for the pod to run again. If it is still on its host it starts there; otherwise it is queued for capacity (on the host its volume is pinned to, if any). The launch gate and quotas apply. Calling it on a pod that is already meant to run changes nothing. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.start(…) Python: client.pods.start(…) Path parameters: - pod_id (required): ID of the pod Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/start" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.start('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.start("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.start pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Stop a pod: compute released and no longer billed; volumes kept (and billed) URL: https://hayonix.ai/docs/reference/pods/stop-pod POST /v1/pods/{pod_id}/stop Stop a pod: compute released and no longer billed; volumes kept (and billed) Stops the container, then releases the pod’s GPUs, CPU and memory; compute billing stops. Only volume data is kept. Calling it on a pod that is already stopped changes nothing. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.stop(…) Python: client.pods.stop(…) Path parameters: - pod_id (required): ID of the pod Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/stop" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.stop('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.stop("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.stop pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Restart the container in place (same host and GPUs; the container disk is kept) URL: https://hayonix.ai/docs/reference/pods/restart-pod POST /v1/pods/{pod_id}/restart Restart the container in place (same host and GPUs; the container disk is kept) Stops and starts the same container on the same host and GPUs, keeping its disk and configuration. Only a pod that is on a host and meant to be running can be restarted (start a stopped one instead); a restart already under way is not repeated. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.restart(…) Python: client.pods.restart(…) Path parameters: - pod_id (required): ID of the pod Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/restart" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.restart('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.restart("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.restart pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Reset a pod: recreate its container from the image with a fresh container disk (volumes kept) URL: https://hayonix.ai/docs/reference/pods/reset-pod POST /v1/pods/{pod_id}/reset Reset a pod: recreate its container from the image with a fresh container disk (volumes kept) Recreates the container in place, on the same host with the same GPUs. Everything written to the container disk is lost, and processes started inside the container end. The pod volume, network volumes, the pod ID, hostname, addresses and settings are kept. Only a pod on a host can be reset (409 `pod_not_running`); a stopped pod already starts with a fresh container disk. A restart in progress becomes a reset. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.reset(…) Python: client.pods.reset(…) Path parameters: - pod_id (required): ID of the pod Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/reset" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.reset('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.reset("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.reset pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Terminate a pod: the container is destroyed; its pod volume is deleted unless kept URL: https://hayonix.ai/docs/reference/pods/terminate-pod POST /v1/pods/{pod_id}/terminate Terminate a pod: the container is destroyed; its pod volume is deleted unless kept Destroys the container and releases its compute for good. The pod’s own volume is deleted unless `keep_volume` is true (a kept volume is still billed); network volumes are not touched. The pod stays readable as `terminated`, and terminating it again changes nothing. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:delete` permission (a key's scope, or a role that includes it). TypeScript: client.pods.terminate(…) Python: client.pods.terminate(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - keep_volume: Keep the pod volume (it can be attached to another pod later; it is still billed) Response: 200 Pod Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/terminate" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "keep_volume": false }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.terminate('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { keep_volume: false }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.terminate("pod_01jc5zq4m8k3v6x9t2w7r0b1e4", keep_volume=False) print(pod) ``` CLI: ```bash hayonix api pods.terminate pod_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"keep_volume":false}' ``` ### Run a command in the pod and wait for it (bounded time and output) URL: https://hayonix.ai/docs/reference/pods/exec-in-pod POST /v1/pods/{pod_id}/exec Run a command in the pod and wait for it (bounded time and output) Runs a command in the running container, without a terminal or input, and returns its exit code and output once it finishes or times out. Each output stream is capped and the excess discarded. Refused unless the pod is running. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.exec(…) Python: client.pods.exec(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - command (required): Program and its arguments, run without a shell (use `["sh", "-c", "…"]` for shell syntax) - working_dir: Directory to run in (default: the image’s working directory) - timeout_seconds: Seconds to wait for the command (default 30); after that the call returns with `timed_out` true Response: 200 PodExecResult Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/exec" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "command": [ "uname", "-a" ], "timeout_seconds": 10 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.exec('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { command: ['uname', '-a'], timeout_seconds: 10 }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.exec( "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", command=["uname", "-a"], timeout_seconds=10, ) print(pod) ``` CLI: ```bash hayonix api pods.exec \ pod_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"command":["uname","-a"],"timeout_seconds":10}' ``` ### A single-use ticket (valid for seconds) to open the pod’s terminal WebSocket URL: https://hayonix.ai/docs/reference/pods/create-pod-terminal-ticket POST /v1/pods/{pod_id}/terminal-tickets A single-use ticket (valid for seconds) to open the pod’s terminal WebSocket Issues a short-lived, single-use ticket for an interactive terminal in the running container, opened as a WebSocket at `websocket_path`. Refused unless the pod is running. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.pods.createTerminalTicket(…) Python: client.pods.create_terminal_ticket(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - rows: Initial terminal height in rows; resize later over the WebSocket - cols: Initial terminal width in columns Response: 200 TerminalTicket Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/terminal-tickets" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rows": 40, "cols": 120 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.createTerminalTicket('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { rows: 40, cols: 120 }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.create_terminal_ticket( "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", rows=40, cols=120, ) print(pod) ``` CLI: ```bash hayonix api pods.createTerminalTicket \ pod_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"rows":40,"cols":120}' ``` ### The pod’s timeline (oldest first): what the platform did and what its host reported URL: https://hayonix.ai/docs/reference/pods/list-pod-events GET /v1/pods/{pod_id}/events The pod’s timeline (oldest first): what the platform did and what its host reported Events such as placement, waiting for capacity, preemption, start and stop requests, reconfiguration and failures, oldest first. Events are kept after the container is gone. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.listEvents(…) Python: client.pods.list_events(…) Path parameters: - pod_id (required): ID of the pod Query parameters: - limit: Events per page, 1–200 (default 100) - cursor: `next_cursor` of the previous page (events are oldest first) Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/events" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.pods.listEvents('pod_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.pods.list_events("pod_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api pods.listEvents pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Container output and platform events as a server-sent event stream URL: https://hayonix.ai/docs/reference/pods/stream-pod-logs GET /v1/pods/{pod_id}/logs Container output and platform events as a server-sent event stream Events: `platform` (a timeline event: id, type, severity, message, occurred_at), `output` (container output: stream stdout|stderr, text, timestamp, instance_id), `notice` (message, e.g. no container on a host yet) and finally `end`. Past output comes from the host (the current container only; it is gone once the container is removed); platform events are kept. With follow=true the stream stays open. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.streamLogs(…) Python: client.pods.stream_logs(…) Path parameters: - pod_id (required): ID of the pod Query parameters: - source: `container`: container output only. `platform`: timeline events only. `all`: both. - follow: Keep the stream open for new output and events - tail: Lines of past container output (and platform events) to start with - since: Start with output and events from this time on (ISO 8601) Response: 200 a server-sent event stream (text/event-stream) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -N "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/logs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const stream = await client.pods.streamLogs('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); for await (const event of stream) { console.log(event.event, event.data); } ``` Python: ```python from hayonix import Client client = Client() for event in client.pods.stream_logs("pod_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(event.event, event.data) ``` CLI: ```bash hayonix api pods.streamLogs pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### CPU, memory, disk, network and GPU series for a time range URL: https://hayonix.ai/docs/reference/pods/get-pod-telemetry GET /v1/pods/{pod_id}/telemetry CPU, memory, disk, network and GPU series for a time range Usage series for a time range (default: the last hour) at a chosen resolution, with totals over the range. Time when the pod was not running has no samples; see `covered_seconds`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:read` permission (a key's scope, or a role that includes it). TypeScript: client.pods.getTelemetry(…) Python: client.pods.get_telemetry(…) Path parameters: - pod_id (required): ID of the pod Query parameters: - from: Default: one hour ago - to: Default: now - resolution: Seconds per point: 10, 60, 300, 900, 3600, 21600 or 86400 (default: the finest giving at most 300 points) Response: 200 PodTelemetry Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/telemetry" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.getTelemetry('pod_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.get_telemetry("pod_01jc5zq4m8k3v6x9t2w7r0b1e4") print(pod) ``` CLI: ```bash hayonix api pods.getTelemetry pod_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Save a pod’s configuration as a template (secrets are dropped from public ones) URL: https://hayonix.ai/docs/reference/pods/save-pod-as-template POST /v1/pods/{pod_id}/templates Save a pod’s configuration as a template (secrets are dropped from public ones) Creates a template from the pod’s image, command, ports, environment, container disk, volume size and mount path and SSH setting. Network volumes are never saved; a public template also leaves out secret references and the registry credential. `omitted` lists what was left out. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:create` permission (a key's scope, or a role that includes it). TypeScript: client.pods.saveAsTemplate(…) Python: client.pods.save_as_template(…) Path parameters: - pod_id (required): ID of the pod Request body (JSON): - name (required): Its name - description: Free-text description - visibility: `private`: every project of your organization can use it. `public`: every organization can; secret references and the registry credential are left out. Response: 201 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/templates" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "My notebook setup", "visibility": "private" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const pod = await client.pods.saveAsTemplate('pod_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'My notebook setup', visibility: 'private' }); console.log(pod); ``` Python: ```python from hayonix import Client client = Client() pod = client.pods.save_as_template( "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", name="My notebook setup", visibility="private", ) print(pod) ``` CLI: ```bash hayonix api pods.saveAsTemplate \ pod_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"name":"My notebook setup","visibility":"private"}' ``` --- ## Templates ### Templates you can launch: official, public and your organization’s private ones URL: https://hayonix.ai/docs/reference/templates/list-templates GET /v1/templates Templates you can launch: official, public and your organization’s private ones Official templates, public templates from any organization and your organization’s private ones, newest first. Deleted templates are left out; narrow the list with `source`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:read` permission (a key's scope, or a role that includes it). TypeScript: client.templates.list(…) Python: client.templates.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - source: `private` lists your organization’s own private templates Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/templates" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.templates.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.templates.list(): print(item) ``` CLI: ```bash hayonix api templates.list ``` ### Create a private (organization) or public template URL: https://hayonix.ai/docs/reference/templates/create-template POST /v1/templates Create a private (organization) or public template Creates a template owned by your organization. A private template is usable by all its projects; a public one by every organization, and it keeps no secret references or registry credential. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:create` permission (a key's scope, or a role that includes it). TypeScript: client.templates.create(…) Python: client.templates.create(…) Request body (JSON): - name (required): Its name - description: Free-text description - image (required): Container image reference - visibility: `private`: every project of your organization can use it. `public`: every organization can; secret references and the registry credential are dropped. - requires_gpu: Pods from it need a GPU SKU (default false) - readme: Usage notes shown with the template (Markdown) - registry_credential_id: ID of the registry credential - defaults: Launch defaults; fields left out take their default values Response: 201 Template Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/templates" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "Team base image", "image": "ubuntu:26.04", "visibility": "private", "defaults": { "command": [ "sleep", "infinity" ], "volume": { "size_gb": 20, "mount_path": "/workspace" } } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const template = await client.templates.create({ name: 'Team base image', image: 'ubuntu:26.04', visibility: 'private', defaults: { command: ['sleep', 'infinity'], volume: { size_gb: 20, mount_path: '/workspace' }, }, }); console.log(template); ``` Python: ```python from hayonix import Client client = Client() template = client.templates.create( name="Team base image", image="ubuntu:26.04", visibility="private", defaults={ "command": ["sleep", "infinity"], "volume": {"size_gb": 20, "mount_path": "/workspace"}, }, ) print(template) ``` CLI: ```bash hayonix api templates.create \ --body '{"name":"Team base image","image":"ubuntu:26.04","visibility":"private","defaults":{"command":["sleep","infinity"],"volume":{"size_gb":20,"mount_path":"/workspace"}}}' ``` ### Get a template URL: https://hayonix.ai/docs/reference/templates/get-template GET /v1/templates/{template_id} Get a template Returns an official or public template, or one of your organization’s private ones. Other organizations’ private templates and deleted templates are not found. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:read` permission (a key's scope, or a role that includes it). TypeScript: client.templates.get(…) Python: client.templates.get(…) Path parameters: - template_id (required): ID of the template Response: 200 Template Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/templates/tpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const template = await client.templates.get('tpl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(template); ``` Python: ```python from hayonix import Client client = Client() template = client.templates.get("tpl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(template) ``` CLI: ```bash hayonix api templates.get tpl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Update one of your organization’s templates (pods made from it are not changed) URL: https://hayonix.ai/docs/reference/templates/update-template PATCH /v1/templates/{template_id} Update one of your organization’s templates (pods made from it are not changed) Only the fields sent change; a list inside `defaults` is replaced whole. Making a template public drops its secret references and registry credential. Official templates and other organizations’ templates cannot be updated. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:update` permission (a key's scope, or a role that includes it). TypeScript: client.templates.update(…) Python: client.templates.update(…) Path parameters: - template_id (required): ID of the template Request body (JSON): - name: Its name - description: Free-text description - image: Container image reference - visibility: `private`: every project of your organization can use it. `public`: every organization can; secret references and the registry credential are dropped. - requires_gpu: Pods from it need a GPU SKU (default false) - readme: Usage notes shown with the template (Markdown) - registry_credential_id: ID of the registry credential - defaults: Only the fields sent change; the others keep their stored values. Send an empty list to clear one (`"secret_env": []`). Response: 200 Template Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/templates/tpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "description": "Updated description" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const template = await client.templates.update('tpl_01jc5zq4m8k3v6x9t2w7r0b1e4', { description: 'Updated description' }); console.log(template); ``` Python: ```python from hayonix import Client client = Client() template = client.templates.update( "tpl_01jc5zq4m8k3v6x9t2w7r0b1e4", description="Updated description", ) print(template) ``` CLI: ```bash hayonix api templates.update \ tpl_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"description":"Updated description"}' ``` ### Delete one of your organization’s templates (pods made from it keep running) URL: https://hayonix.ai/docs/reference/templates/delete-template DELETE /v1/templates/{template_id} Delete one of your organization’s templates (pods made from it keep running) Removes the template from the catalog so no new pods can be created from it; the response carries its `deleted_at`. Pods already created from it are unaffected. Official templates and other organizations’ templates cannot be deleted. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `template:delete` permission (a key's scope, or a role that includes it). TypeScript: client.templates.delete(…) Python: client.templates.delete(…) Path parameters: - template_id (required): ID of the template Response: 200 Template Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/templates/tpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const template = await client.templates.delete('tpl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(template); ``` Python: ```python from hayonix import Client client = Client() template = client.templates.delete("tpl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(template) ``` CLI: ```bash hayonix api templates.delete tpl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Volumes ### List live volumes in the project URL: https://hayonix.ai/docs/reference/volumes/list-volumes GET /v1/volumes List live volumes in the project Pod volumes and network volumes of the project that have not been deleted, newest first, each with the pods that mount it. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:read` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.list(…) Python: client.volumes.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - kind: Only pod volumes or only network volumes (default: both) Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.volumes.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.volumes.list(): print(item) ``` CLI: ```bash hayonix api volumes.list ``` ### Create a network volume (billed per GB-second until deleted) URL: https://hayonix.ai/docs/reference/volumes/create-volume POST /v1/volumes Create a network volume (billed per GB-second until deleted) Creates an empty network volume in a region, with a name unique in the project. It is not on any host until a pod first mounts it; from then on it is pinned to that host. Storage is billed from now until it is deleted, attached or not. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:create` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.create(…) Python: client.volumes.create(…) Request body (JSON): - name (required): Its name - size_gb (required): Size in GB - region (required): Region code Response: 201 Volume Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "datasets", "size_gb": 50, "region": "dev-local-1" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.create({ name: 'datasets', size_gb: 50, region: 'dev-local-1' }); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.create(name="datasets", size_gb=50, region="dev-local-1") print(volume) ``` CLI: ```bash hayonix api volumes.create \ --body '{"name":"datasets","size_gb":50,"region":"dev-local-1"}' ``` ### Get a volume, where it is pinned and which pods mount it URL: https://hayonix.ai/docs/reference/volumes/get-volume GET /v1/volumes/{volume_id} Get a volume, where it is pinned and which pods mount it Returns the volume’s size, status, whether it is pinned to a host, the pods that mount it and how it is billed. Deleted volumes stay readable. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:read` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.get(…) Python: client.volumes.get(…) Path parameters: - volume_id (required): ID of the volume Response: 200 Volume Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.get('vol_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.get("vol_01jc5zq4m8k3v6x9t2w7r0b1e4") print(volume) ``` CLI: ```bash hayonix api volumes.get vol_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Rename a volume URL: https://hayonix.ai/docs/reference/volumes/rename-volume PATCH /v1/volumes/{volume_id} Rename a volume Changes the name, which must be unique in the project; the data and the pods that mount it are not affected. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:update` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.rename(…) Python: client.volumes.rename(…) Path parameters: - volume_id (required): ID of the volume Request body (JSON): - name (required): Its name Response: 200 Volume Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "datasets-v2" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.rename('vol_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'datasets-v2' }); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.rename("vol_01jc5zq4m8k3v6x9t2w7r0b1e4", name="datasets-v2") print(volume) ``` CLI: ```bash hayonix api volumes.rename vol_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"name":"datasets-v2"}' ``` ### Delete an unattached volume and its data (irreversible; billing stops now) URL: https://hayonix.ai/docs/reference/volumes/delete-volume DELETE /v1/volumes/{volume_id} Delete an unattached volume and its data (irreversible; billing stops now) Deletes the volume and its data for good, and storage billing stops at once. Refused (409 `volume_attached`) while any pod or serverless endpoint mounts it: detach it, terminate those pods, or remove it from the endpoint’s release first. The status is `deleting` until its host has removed the data, then `deleted`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:delete` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.delete(…) Python: client.volumes.delete(…) Path parameters: - volume_id (required): ID of the volume Response: 200 Volume Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.delete('vol_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.delete("vol_01jc5zq4m8k3v6x9t2w7r0b1e4") print(volume) ``` CLI: ```bash hayonix api volumes.delete vol_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Grow a volume (sizes never shrink) URL: https://hayonix.ai/docs/reference/volumes/grow-volume POST /v1/volumes/{volume_id}/grow Grow a volume (sizes never shrink) Raises the size to `size_gb`, which must be larger than the current size. The time so far is billed at the old size and the new size from now on. Refused when the organization may not add storage or the storage quota would be exceeded. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `volume:update` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.grow(…) Python: client.volumes.grow(…) Path parameters: - volume_id (required): ID of the volume Request body (JSON): - size_gb (required): New size in GB; must be larger than the current size Response: 200 Volume Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4/grow" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "size_gb": 100 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.grow('vol_01jc5zq4m8k3v6x9t2w7r0b1e4', { size_gb: 100 }); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.grow("vol_01jc5zq4m8k3v6x9t2w7r0b1e4", size_gb=100) print(volume) ``` CLI: ```bash hayonix api volumes.grow vol_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"size_gb":100}' ``` ### Mount the volume in a pod (recreates the pod’s container; see the plan) URL: https://hayonix.ai/docs/reference/volumes/attach-volume POST /v1/volumes/{volume_id}/attach Mount the volume in a pod (recreates the pod’s container; see the plan) Adds the volume to the pod’s configuration: a network volume joins the pod’s other network volumes (attaching it again changes its mount path or mode); a pod volume replaces the pod’s own volume. This is a reconfiguration, so the container is recreated and the pod may move to the volume’s host. Use `dry_run` to see the plan first. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.attach(…) Python: client.volumes.attach(…) Path parameters: - volume_id (required): ID of the volume Request body (JSON): - pod_id (required): ID of the pod - mount_path (required): Absolute path the volume is mounted at inside the container - read_only: Mount read-only (network volumes only; a pod volume is always writable) - dry_run: Only report what would change (nothing is applied) Response: 200 PodReconfiguration Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4/attach" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pod_id": "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", "mount_path": "/data", "dry_run": true }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.attach('vol_01jc5zq4m8k3v6x9t2w7r0b1e4', { pod_id: 'pod_01jc5zq4m8k3v6x9t2w7r0b1e4', mount_path: '/data', dry_run: true, }); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.attach( "vol_01jc5zq4m8k3v6x9t2w7r0b1e4", pod_id="pod_01jc5zq4m8k3v6x9t2w7r0b1e4", mount_path="/data", dry_run=True, ) print(volume) ``` CLI: ```bash hayonix api volumes.attach \ vol_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"pod_id":"pod_01jc5zq4m8k3v6x9t2w7r0b1e4","mount_path":"/data","dry_run":true}' ``` ### Unmount the volume from a pod (recreates the pod’s container; the data is kept) URL: https://hayonix.ai/docs/reference/volumes/detach-volume POST /v1/volumes/{volume_id}/detach Unmount the volume from a pod (recreates the pod’s container; the data is kept) Removes the volume from the pod’s configuration; the volume and its data are kept and still billed. This is a reconfiguration, so the pod’s container is recreated. Refused when the volume is not mounted in that pod. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `workload:update` permission (a key's scope, or a role that includes it). TypeScript: client.volumes.detach(…) Python: client.volumes.detach(…) Path parameters: - volume_id (required): ID of the volume Request body (JSON): - pod_id (required): ID of the pod - dry_run: Only report what would change (nothing is applied) Response: 200 PodReconfiguration Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4/detach" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pod_id": "pod_01jc5zq4m8k3v6x9t2w7r0b1e4", "dry_run": true }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const volume = await client.volumes.detach('vol_01jc5zq4m8k3v6x9t2w7r0b1e4', { pod_id: 'pod_01jc5zq4m8k3v6x9t2w7r0b1e4', dry_run: true }); console.log(volume); ``` Python: ```python from hayonix import Client client = Client() volume = client.volumes.detach( "vol_01jc5zq4m8k3v6x9t2w7r0b1e4", pod_id="pod_01jc5zq4m8k3v6x9t2w7r0b1e4", dry_run=True, ) print(volume) ``` CLI: ```bash hayonix api volumes.detach \ vol_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"pod_id":"pod_01jc5zq4m8k3v6x9t2w7r0b1e4","dry_run":true}' ``` --- ## Serverless ### List serverless endpoints in the project URL: https://hayonix.ai/docs/reference/serverless/list-serverless-endpoints GET /v1/serverless/endpoints List serverless endpoints in the project Each endpoint comes with its settings and current release. Deleted endpoints are not listed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.listEndpoints(…) Python: client.serverless.list_endpoints(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.serverless.listEndpoints()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.serverless.list_endpoints(): print(item) ``` CLI: ```bash hayonix api serverless.listEndpoints ``` ### Create a serverless endpoint (the webhook secret is returned once) URL: https://hayonix.ai/docs/reference/serverless/create-serverless-endpoint POST /v1/serverless/endpoints Create a serverless endpoint (the webhook secret is returned once) 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. Authentication: 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). TypeScript: client.serverless.createEndpoint(…) Python: client.serverless.create_endpoint(…) Request body (JSON): - name (required): Its name - mode: `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. - region: Region code - image (required): Container image reference - registry_credential_id: ID of the registry credential - command: Replaces the image's entrypoint (default: the image's own) - args: Replaces the image's default arguments (default: the image's own) - env: Environment variables of every worker. Names starting with `WORKER_RUNTIME_` are reserved for the platform. - skus (required): Acceptable hardware in order of preference; workers take the first with capacity - gpu_count: GPUs per worker on GPU SKUs - concurrency: Jobs (queue endpoints, 1–64) or requests (HTTP endpoints, 1–1000) one worker takes at once (default 1) - disk_bytes: Limit on each worker container's writable disk, in bytes (default 0: no limit beyond the host's) - models: Models from the model hub the worker reads (one revision per repository) - http: HTTP endpoints only (required for them): where the container serves - volumes: 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. - min_workers: Default 0 - max_workers: Default 3 - idle_timeout_seconds: An idle worker is removed after this (default 30) - execution_timeout_seconds: Per job (default 600) - queue_ttl_seconds: A job not started within this expires (default 86400) - result_ttl_seconds: Results are kept this long after a job finishes (default 3600) - max_retries: Re-runs after a lost worker before the job fails (default 2) - scaling - webhook_url: Default completion webhook for jobs of this endpoint - cold_start_wait_seconds: 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) - drain_timeout_seconds: HTTP endpoints: a worker leaving rotation (scale-down, new release) gets this long to finish the requests it has in flight (default 60) - fast_resume Response: 201 CreatedServerlessEndpoint Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash 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 } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.createEndpoint({ 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 }, }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.create_endpoint( 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}, ) print(result) ``` CLI: ```bash hayonix api serverless.createEndpoint \ --body '{"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}}' ``` ### Get a serverless endpoint URL: https://hayonix.ai/docs/reference/serverless/get-serverless-endpoint GET /v1/serverless/endpoints/{endpoint_id} Get a serverless endpoint The endpoint with its scaling and job settings, its URL (HTTP endpoints) and its current release. A deleted endpoint is 404. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getEndpoint(…) Python: client.serverless.get_endpoint(…) Path parameters: - endpoint_id (required): ID of the endpoint Response: 200 ServerlessEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getEndpoint('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_endpoint("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getEndpoint sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Update 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). URL: https://hayonix.ai/docs/reference/serverless/update-serverless-endpoint PATCH /v1/serverless/endpoints/{endpoint_id} Update 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). Only the fields you send change. Scaling and job settings apply at once without replacing any worker; new job limits apply to jobs submitted afterwards. Sending a worker spec identical to the current one creates no release. Authentication: 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). TypeScript: client.serverless.updateEndpoint(…) Python: client.serverless.update_endpoint(…) Path parameters: - endpoint_id (required): ID of the endpoint Request body (JSON): - name: Its name - image: Container image reference - registry_credential_id: ID of the registry credential - command: Replaces the image's entrypoint (default: the image's own) - args: Replaces the image's default arguments (default: the image's own) - env: Environment variables of every worker. Names starting with `WORKER_RUNTIME_` are reserved for the platform. - skus: Acceptable hardware in order of preference; workers take the first with capacity - gpu_count: GPUs per worker on GPU SKUs - concurrency: Jobs (queue endpoints, 1–64) or requests (HTTP endpoints, 1–1000) one worker takes at once (default 1) - disk_bytes: Limit on each worker container's writable disk, in bytes (default 0: no limit beyond the host's) - models: Models from the model hub the worker reads (one revision per repository) - http: HTTP endpoints only (required for them): where the container serves - volumes: 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. - min_workers: Default 0 - max_workers: Default 3 - idle_timeout_seconds: An idle worker is removed after this (default 30) - execution_timeout_seconds: Per job (default 600) - queue_ttl_seconds: A job not started within this expires (default 86400) - result_ttl_seconds: Results are kept this long after a job finishes (default 3600) - max_retries: Re-runs after a lost worker before the job fails (default 2) - scaling - webhook_url: Default completion webhook for jobs of this endpoint - cold_start_wait_seconds: 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) - drain_timeout_seconds: HTTP endpoints: a worker leaving rotation (scale-down, new release) gets this long to finish the requests it has in flight (default 60) - fast_resume Response: 200 ServerlessEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "max_workers": 5, "image": "registry.example.com/team/captioner:1.1.0" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.updateEndpoint('sep_01jc5zq4m8k3v6x9t2w7r0b1e4', { max_workers: 5, image: 'registry.example.com/team/captioner:1.1.0', }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.update_endpoint( "sep_01jc5zq4m8k3v6x9t2w7r0b1e4", max_workers=5, image="registry.example.com/team/captioner:1.1.0", ) print(result) ``` CLI: ```bash hayonix api serverless.updateEndpoint \ sep_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"max_workers":5,"image":"registry.example.com/team/captioner:1.1.0"}' ``` ### Delete an endpoint: its jobs are canceled and its workers removed URL: https://hayonix.ai/docs/reference/serverless/delete-serverless-endpoint DELETE /v1/serverless/endpoints/{endpoint_id} Delete an endpoint: its jobs are canceled and its workers removed Takes effect at once: queued and running jobs end as `canceled` with code `endpoint_deleted` (running handlers are told to stop), and every worker is drained and removed. The name becomes free for a new endpoint. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:delete` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.deleteEndpoint(…) Python: client.serverless.delete_endpoint(…) Path parameters: - endpoint_id (required): ID of the endpoint Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.deleteEndpoint('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.delete_endpoint("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.deleteEndpoint sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Replace the webhook signing secret (returned once) URL: https://hayonix.ai/docs/reference/serverless/rotate-serverless-webhook-secret POST /v1/serverless/endpoints/{endpoint_id}/rotate-webhook-secret Replace the webhook signing secret (returned once) The old secret stops signing at once: every delivery sent afterwards, retries included, is signed with the new one only. Update your receiver right after rotating. Authentication: 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). TypeScript: client.serverless.rotateWebhookSecret(…) Python: client.serverless.rotate_webhook_secret(…) Path parameters: - endpoint_id (required): ID of the endpoint Response: 200 ServerlessWebhookSecret Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/rotate-webhook-secret" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.rotateWebhookSecret('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.rotate_webhook_secret("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.rotateWebhookSecret sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Release history, newest first URL: https://hayonix.ai/docs/reference/serverless/list-serverless-releases GET /v1/serverless/endpoints/{endpoint_id}/releases Release history, newest first Every worker spec the endpoint has had (at most the 200 most recent). Releases never change; pass one to rollback to run its spec again. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.listReleases(…) Python: client.serverless.list_releases(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/releases" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.serverless.listReleases('sep_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.serverless.list_releases("sep_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api serverless.listReleases sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Get a release URL: https://hayonix.ai/docs/reference/serverless/get-serverless-release GET /v1/serverless/releases/{release_id} Get a release One release: its worker spec, which never changes, and its rollout status. Secret environment variables appear only as references. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getRelease(…) Python: client.serverless.get_release(…) Path parameters: - release_id (required): ID of the release Response: 200 ServerlessRelease Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/releases/srl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getRelease('srl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_release("srl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getRelease srl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Roll back: a new release with an earlier release's worker spec URL: https://hayonix.ai/docs/reference/serverless/rollback-serverless-endpoint POST /v1/serverless/endpoints/{endpoint_id}/rollback Roll back: a new release with an earlier release's worker spec 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. Authentication: 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). TypeScript: client.serverless.rollbackEndpoint(…) Python: client.serverless.rollback_endpoint(…) Path parameters: - endpoint_id (required): ID of the endpoint Request body (JSON): - release_id (required): ID of the release Response: 201 ServerlessRelease Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash 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" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.rollbackEndpoint('sep_01jc5zq4m8k3v6x9t2w7r0b1e4', { release_id: 'srl_01jc5zq4m8k3v6x9t2w7r0b1e4' }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.rollback_endpoint( "sep_01jc5zq4m8k3v6x9t2w7r0b1e4", release_id="srl_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(result) ``` CLI: ```bash hayonix api serverless.rollbackEndpoint \ sep_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"release_id":"srl_01jc5zq4m8k3v6x9t2w7r0b1e4"}' ``` ### List jobs of an endpoint, newest first URL: https://hayonix.ai/docs/reference/serverless/list-serverless-jobs GET /v1/serverless/endpoints/{endpoint_id}/jobs List jobs of an endpoint, newest first Jobs without their input or attempt history (fetch one job for those). Filter by `state` to find queued or failed jobs. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.listJobs(…) Python: client.serverless.list_jobs(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - state: Only jobs in this state Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/jobs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.serverless.listJobs('sep_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.serverless.list_jobs("sep_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api serverless.listJobs sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Submit a job. With `wait`, answer once it finishes or the wait runs out (then poll the job). URL: https://hayonix.ai/docs/reference/serverless/submit-serverless-job POST /v1/serverless/endpoints/{endpoint_id}/jobs Submit a job. With `wait`, answer once it finishes or the wait runs out (then poll the job). The job is queued as soon as it is accepted, also while the call waits. A retry with the same `Idempotency-Key` never creates a second job: it answers with that job in its current state, waiting again if it carries `wait`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_job:create` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.submitJob(…) Python: client.serverless.submit_job(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - wait: Wait up to this many seconds (≤ 60) for the job to finish before answering; poll the job afterwards if it has not Request body (JSON): - input: Any JSON, at most 1048576 bytes serialised - webhook_url: Completion webhook for this job (default: the endpoint's; null for none) - policy: Lower the endpoint's limits for this job Response: 201 ServerlessJob Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/jobs" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "input": { "prompt": "a red bicycle" } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.submitJob('sep_01jc5zq4m8k3v6x9t2w7r0b1e4', { input: { prompt: 'a red bicycle' } }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.submit_job( "sep_01jc5zq4m8k3v6x9t2w7r0b1e4", input={"prompt": "a red bicycle"}, ) print(result) ``` CLI: ```bash hayonix api serverless.submitJob \ sep_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"input":{"prompt":"a red bicycle"}}' ``` ### Job status and result. With `wait`, long-poll until it finishes. URL: https://hayonix.ai/docs/reference/serverless/get-serverless-job GET /v1/serverless/jobs/{job_id} Job status and result. With `wait`, long-poll until it finishes. Includes the input and every finished attempt. With `wait`, the answer comes as soon as the job reaches a final state or the wait runs out, whichever is first. The result is kept until `result_expires_at`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getJob(…) Python: client.serverless.get_job(…) Path parameters: - job_id (required): ID of the job Query parameters: - wait: Wait up to this many seconds for the job to finish Response: 200 ServerlessJob Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/jobs/sjb_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getJob('sjb_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_job("sjb_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getJob sjb_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Partial output streamed by the handler, in order (long-poll with `wait`) URL: https://hayonix.ai/docs/reference/serverless/stream-serverless-job GET /v1/serverless/jobs/{job_id}/stream Partial output streamed by the handler, in order (long-poll with `wait`) Returns the chunks of the current attempt after `after`, up to 200 at a time; call again with `next_after` until `done` is true. If the job is retried, the stream starts over with the new attempt (watch `attempt`). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.streamJob(…) Python: client.serverless.stream_job(…) Path parameters: - job_id (required): ID of the job Query parameters: - after: Return chunks with a sequence number above this (`next_after` of the previous page) - wait: Long-poll up to this many seconds for new chunks Response: 200 ServerlessJobStream Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/jobs/sjb_01jc5zq4m8k3v6x9t2w7r0b1e4/stream" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.streamJob('sjb_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.stream_job("sjb_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.streamJob sjb_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Cancel a queued or running job (a running handler is told to stop) URL: https://hayonix.ai/docs/reference/serverless/cancel-serverless-job POST /v1/serverless/jobs/{job_id}/cancel Cancel a queued or running job (a running handler is told to stop) The job ends as `canceled` at once; a running handler learns it on its next heartbeat. Canceling a canceled job returns it unchanged; a job that already finished otherwise is a conflict. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_job:update` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.cancelJob(…) Python: client.serverless.cancel_job(…) Path parameters: - job_id (required): ID of the job Response: 200 ServerlessJob Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/serverless/jobs/sjb_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.cancelJob('sjb_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.cancel_job("sjb_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.cancelJob sjb_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Cancel every queued job of the endpoint (running jobs continue) URL: https://hayonix.ai/docs/reference/serverless/purge-serverless-queue POST /v1/serverless/endpoints/{endpoint_id}/purge-queue Cancel every queued job of the endpoint (running jobs continue) Every job still `queued` ends as `canceled` with code `purged`; jobs with a webhook URL get their completion webhook. Safe to repeat: purging an empty queue cancels 0. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_job:delete` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.purgeQueue(…) Python: client.serverless.purge_queue(…) Path parameters: - endpoint_id (required): ID of the endpoint Response: 200 ServerlessQueuePurge Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/purge-queue" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.purgeQueue('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.purge_queue("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.purgeQueue sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Queue depth, jobs by state, workers by state and rollout progress URL: https://hayonix.ai/docs/reference/serverless/get-serverless-endpoint-health GET /v1/serverless/endpoints/{endpoint_id}/health Queue depth, jobs by state, workers by state and rollout progress A snapshot taken now. `launch` explains queued jobs that no worker picks up (credit, spend limit, suspension or worker quota); `requests` covers HTTP endpoints' live traffic. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getEndpointHealth(…) Python: client.serverless.get_endpoint_health(…) Path parameters: - endpoint_id (required): ID of the endpoint Response: 200 ServerlessEndpointHealth Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/health" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getEndpointHealth('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_endpoint_health("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getEndpointHealth sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Queue delay, execution time, cold starts and job counts over time URL: https://hayonix.ai/docs/reference/serverless/get-serverless-endpoint-metrics GET /v1/serverless/endpoints/{endpoint_id}/metrics Queue delay, execution time, cold starts and job counts over time Fixed buckets over a window ending now: the last hour in 1-minute buckets by default. The window is 60 seconds to 30 days, buckets are at least 10 seconds, and a call returns at most 1000 buckets. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getEndpointMetrics(…) Python: client.serverless.get_endpoint_metrics(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - window_seconds: Default 3600 - bucket_seconds: Default 60 Response: 200 ServerlessEndpointMetrics Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/metrics" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getEndpointMetrics('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_endpoint_metrics("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getEndpointMetrics sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### HTTP endpoints: request rate, status classes, latency percentiles, requests in flight and cold-start waits over time, per endpoint and per worker URL: https://hayonix.ai/docs/reference/serverless/get-serverless-endpoint-request-metrics GET /v1/serverless/endpoints/{endpoint_id}/request-metrics HTTP endpoints: request rate, status classes, latency percentiles, requests in flight and cold-start waits over time, per endpoint and per worker Measured where requests enter the platform, over a window ending now: the last hour in 1-minute buckets by default. The window is 60 seconds to 14 days, buckets are at least 10 seconds, and a call returns at most 1000 buckets. Queue endpoints have no request traffic, so their buckets are empty. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getEndpointRequestMetrics(…) Python: client.serverless.get_endpoint_request_metrics(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - window_seconds: Default 3600 - bucket_seconds: Default 60 - worker_id: One worker only Response: 200 ServerlessEndpointRequestMetrics Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/request-metrics" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getEndpointRequestMetrics('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_endpoint_request_metrics("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getEndpointRequestMetrics sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Workers of the endpoint with their state (live ones and those removed in the last hour) URL: https://hayonix.ai/docs/reference/serverless/list-serverless-workers GET /v1/serverless/endpoints/{endpoint_id}/workers Workers of the endpoint with their state (live ones and those removed in the last hour) At most 500 workers. Use `live=true` to leave out removed workers; for a worker that is not starting, `scheduling_status` and `scheduling_message` say why. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.listWorkers(…) Python: client.serverless.list_workers(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - live: Only workers that are not terminated Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/workers" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.serverless.listWorkers('sep_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.serverless.list_workers("sep_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api serverless.listWorkers sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Recent container logs of the endpoint's workers URL: https://hayonix.ai/docs/reference/serverless/get-serverless-worker-logs GET /v1/serverless/endpoints/{endpoint_id}/logs Recent container logs of the endpoint's workers The last `tail` lines of each live worker, or of one worker with `worker_id`. A worker whose logs cannot be read is listed in `errors` instead of failing the request. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.getWorkerLogs(…) Python: client.serverless.get_worker_logs(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - worker_id: One worker (default: every live worker) - tail: Lines per worker (default 100) Response: 200 ServerlessWorkerLogs Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/logs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.serverless.getWorkerLogs('sep_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.serverless.get_worker_logs("sep_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api serverless.getWorkerLogs sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Completion webhook deliveries with their attempt log, newest first URL: https://hayonix.ai/docs/reference/serverless/list-serverless-webhook-deliveries GET /v1/serverless/endpoints/{endpoint_id}/webhook-deliveries Completion webhook deliveries with their attempt log, newest first One delivery per finished job that had a webhook URL, with its status and every attempt (status code, error, duration). Use it to see why your receiver did not get a job's result. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `serverless_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.serverless.listWebhookDeliveries(…) Python: client.serverless.list_webhook_deliveries(…) Path parameters: - endpoint_id (required): ID of the endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/serverless/endpoints/sep_01jc5zq4m8k3v6x9t2w7r0b1e4/webhook-deliveries" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.serverless.listWebhookDeliveries('sep_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.serverless.list_webhook_deliveries("sep_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api serverless.listWebhookDeliveries sep_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Models ### List catalog models (public ones; with credentials, also the project's private ones) URL: https://hayonix.ai/docs/reference/models/list-catalog-models GET /v1/catalog/models List catalog models (public ones; with credentials, also the project's private ones) Works without credentials. Each model carries its prices from the price book in force, its context length, capabilities and whether a replica is serving it right now. With an API key, or a session plus `X-Project-Id`, the list also includes that project's private models (fine-tuned models and dedicated endpoints). Authentication: None: this operation is public. TypeScript: client.models.list(…) Python: client.models.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - type: Only models of this type Response: 200 a page of results Errors: - 400 invalid_request_error: A parameter or body field is missing or not allowed; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/catalog/models" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.models.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.models.list(): print(item) ``` CLI: ```bash hayonix api models.list ``` ### Get a catalog model (private models only for their own project) URL: https://hayonix.ai/docs/reference/models/get-catalog-model GET /v1/catalog/models/{model_id} Get a catalog model (private models only for their own project) Works without credentials for public models. A private model is returned only to callers with credentials for the project that owns it; to anyone else it is 404, as if it did not exist. Authentication: None: this operation is public. TypeScript: client.models.get(…) Python: client.models.get(…) Path parameters: - model_id (required): ID of the model Response: 200 CatalogModel Errors: - 400 invalid_request_error: A parameter or body field is missing or not allowed; `param` names it. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/catalog/models/mdl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const model = await client.models.get('mdl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(model); ``` Python: ```python from hayonix import Client client = Client() model = client.models.get("mdl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(model) ``` CLI: ```bash hayonix api models.get mdl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Mint a short-lived playground token for the inference API (signed-in users only) URL: https://hayonix.ai/docs/reference/models/create-playground-token POST /v1/playground-tokens Mint a short-lived playground token for the inference API (signed-in users only) Returns a bearer token that calls the inference API on behalf of the signed-in user in this project, for trying models from the console. It expires after `ttl_seconds` (15 minutes by default) and is shown only in this response. API keys cannot mint one. Authentication: Console session only. The console calls this with a signed-in session; API keys are refused. Requires the `inference:invoke` permission (a key's scope, or a role that includes it). Request body (JSON): - ttl_seconds: Lifetime in seconds (30–900, default 900) Response: 201 PlaygroundToken Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. --- ## Model references ### List the project’s model references URL: https://hayonix.ai/docs/reference/model-references/list-model-references GET /v1/model-references List the project’s model references The project’s model references, newest first. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `model_reference:read` permission (a key's scope, or a role that includes it). TypeScript: client.modelReferences.list(…) Python: client.model_references.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/model-references" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.modelReferences.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.model_references.list(): print(item) ``` CLI: ```bash hayonix api modelReferences.list ``` ### Accept a model reference (checked against the model hub, pinned to a commit) URL: https://hayonix.ai/docs/reference/model-references/create-model-reference POST /v1/model-references Accept a model reference (checked against the model hub, pinned to a commit) Checks a model on the model hub and records it for this project: the revision is pinned to its commit, and the files (all, or those matching include) are listed with their sizes and digests. Nothing is downloaded now; hosts download and verify the files when a workload that mounts the reference starts. A private or gated model needs token_secret_id; its files are then cached for this project only. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `model_reference:create` permission (a key's scope, or a role that includes it). TypeScript: client.modelReferences.create(…) Python: client.model_references.create(…) Request body (JSON): - model (required): The model on the model hub, as / or /@. The revision (a branch, tag or commit; default main) is pinned to its commit now, so a moving branch never changes what runs. - include: Only files matching one of these patterns (`*` matches any characters including "/", `?` one character). Default: every file of the revision. - token_secret_id: A project secret holding a model hub access token, for private or gated repositories. Hosts download with it and keep the files for this project only; containers never see it. Response: 201 ModelReference Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/model-references" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "hf-internal-testing/tiny-random-gpt2@main", "include": [ "*.json", "*.safetensors" ] }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const reference = await client.modelReferences.create({ model: 'hf-internal-testing/tiny-random-gpt2@main', include: ['*.json', '*.safetensors'], }); console.log(reference); ``` Python: ```python from hayonix import Client client = Client() reference = client.model_references.create( model="hf-internal-testing/tiny-random-gpt2@main", include=["*.json", "*.safetensors"], ) print(reference) ``` CLI: ```bash hayonix api modelReferences.create \ --body '{"model":"hf-internal-testing/tiny-random-gpt2@main","include":["*.json","*.safetensors"]}' ``` ### Get a model reference and the files it resolved to URL: https://hayonix.ai/docs/reference/model-references/get-model-reference GET /v1/model-references/{reference_id} Get a model reference and the files it resolved to What a model reference resolved to: its commit and every file with its size and digest. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `model_reference:read` permission (a key's scope, or a role that includes it). TypeScript: client.modelReferences.get(…) Python: client.model_references.get(…) Path parameters: - reference_id (required): ID of the reference Response: 200 ModelReference Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/model-references/mrf_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const reference = await client.modelReferences.get('mrf_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(reference); ``` Python: ```python from hayonix import Client client = Client() reference = client.model_references.get("mrf_01jc5zq4m8k3v6x9t2w7r0b1e4") print(reference) ``` CLI: ```bash hayonix api modelReferences.get mrf_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Delete a model reference nothing mounts URL: https://hayonix.ai/docs/reference/model-references/delete-model-reference DELETE /v1/model-references/{reference_id} Delete a model reference nothing mounts Deletes a model reference. Refused (409) while a workload mounts it or a serverless endpoint’s current release names it. Hosts drop its files as their caches need the room. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `model_reference:delete` permission (a key's scope, or a role that includes it). TypeScript: client.modelReferences.delete(…) Python: client.model_references.delete(…) Path parameters: - reference_id (required): ID of the reference Response: 200 DeletedModelReference Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/model-references/mrf_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const reference = await client.modelReferences.delete('mrf_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(reference); ``` Python: ```python from hayonix import Client client = Client() reference = client.model_references.delete("mrf_01jc5zq4m8k3v6x9t2w7r0b1e4") print(reference) ``` CLI: ```bash hayonix api modelReferences.delete mrf_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Dedicated endpoints ### List dedicated endpoints in the project, newest first URL: https://hayonix.ai/docs/reference/dedicated-endpoints/list-dedicated-endpoints GET /v1/endpoints List dedicated endpoints in the project, newest first Each endpoint comes with its deployments, their replica counts and the endpoint's current status. Deleted endpoints are not listed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.list(…) Python: client.dedicated_endpoints.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.dedicatedEndpoints.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.dedicated_endpoints.list(): print(item) ``` CLI: ```bash hayonix api dedicatedEndpoints.list ``` ### Create a dedicated endpoint (a catalog model or your own Hugging Face model) with its first deployment URL: https://hayonix.ai/docs/reference/dedicated-endpoints/create-dedicated-endpoint POST /v1/endpoints Create a dedicated endpoint (a catalog model or your own Hugging Face model) with its first deployment Creates the endpoint, its model ID `/` (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. Authentication: 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). TypeScript: client.dedicatedEndpoints.create(…) Python: client.dedicated_endpoints.create(…) Request body (JSON): - name (required): Lowercase letters, digits and hyphens. The model ID is `/`. - display_name: Name to show people - inactivity_timeout_seconds: Stop after this long without a request (0: never; default 3600) - start: Start serving now (default true) - deployment_name: Name of the first deployment (default `primary`) - model (required): Model ID (`publisher/name`) - hardware (required) - region: Region code - engine - engine_options - disk_gb: Room for the weights (default 10 on CPU, 200 on GPU) - min_replicas: Default 1 - max_replicas: Default 1 - autoscaling Response: 201 DedicatedEndpoint Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash 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 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.create({ 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, }); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.create( 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, ) print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.create \ --body '{"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}' ``` ### Get a dedicated endpoint with its deployments and replica counts URL: https://hayonix.ai/docs/reference/dedicated-endpoints/get-dedicated-endpoint GET /v1/endpoints/{dedicated_endpoint_id} Get a dedicated endpoint with its deployments and replica counts The status is worked out from the replicas at the time of the request, so poll this to wait for an endpoint to reach `serving`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.get(…) Python: client.dedicated_endpoints.get(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Response: 200 DedicatedEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.get('ded_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.get("ded_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.get ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Update the display name or the inactivity timeout URL: https://hayonix.ai/docs/reference/dedicated-endpoints/update-dedicated-endpoint PATCH /v1/endpoints/{dedicated_endpoint_id} Update the display name or the inactivity timeout Only the fields you send change, and running replicas are not touched. The inactivity timeout counts from the later of the last request and the last start, so a shorter one can stop a quiet endpoint soon after the change. Authentication: 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). TypeScript: client.dedicatedEndpoints.update(…) Python: client.dedicated_endpoints.update(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Request body (JSON): - display_name: Name to show people - inactivity_timeout_seconds: Stop after this many seconds without a request (0: never; otherwise 60–604800) Response: 200 DedicatedEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inactivity_timeout_seconds": 1800 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.update('ded_01jc5zq4m8k3v6x9t2w7r0b1e4', { inactivity_timeout_seconds: 1800 }); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.update( "ded_01jc5zq4m8k3v6x9t2w7r0b1e4", inactivity_timeout_seconds=1800, ) print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.update \ ded_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"inactivity_timeout_seconds":1800}' ``` ### Delete an endpoint: its replicas are removed and its model ID stops resolving URL: https://hayonix.ai/docs/reference/dedicated-endpoints/delete-dedicated-endpoint DELETE /v1/endpoints/{dedicated_endpoint_id} Delete an endpoint: its replicas are removed and its model ID stops resolving Takes effect at once: requests for its model ID stop being routed, every replica is drained and removed, and replica billing ends. The name becomes free for a new endpoint; past charges stay in the billing history. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:delete` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.delete(…) Python: client.dedicated_endpoints.delete(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.delete('ded_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.delete("ded_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.delete ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Start a stopped endpoint (needs credit; replicas start and are billed once ready) URL: https://hayonix.ai/docs/reference/dedicated-endpoints/start-dedicated-endpoint POST /v1/endpoints/{dedicated_endpoint_id}/start Start a stopped endpoint (needs credit; replicas start and are billed once ready) Asks for the endpoint to run and gives deployments that had given up after failed starts a fresh try. Refused when the organization is out of credit or over its quotas. Starting an endpoint that is already running changes nothing. Authentication: 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). TypeScript: client.dedicatedEndpoints.start(…) Python: client.dedicated_endpoints.start(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Response: 200 DedicatedEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/start" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.start('ded_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.start("ded_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.start ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Stop an endpoint: its replicas are removed and billing for them ends URL: https://hayonix.ai/docs/reference/dedicated-endpoints/stop-dedicated-endpoint POST /v1/endpoints/{dedicated_endpoint_id}/stop Stop an endpoint: its replicas are removed and billing for them ends Requests stop being routed to the endpoint at once; its replicas then drain and are removed (status `stopping`, then `stopped`). Deployments and settings are kept for a later start. Stopping a stopped endpoint changes nothing. Authentication: 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). TypeScript: client.dedicatedEndpoints.stop(…) Python: client.dedicated_endpoints.stop(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Response: 200 DedicatedEndpoint Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/stop" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.stop('ded_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.stop("ded_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.stop ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### An endpoint's deployments URL: https://hayonix.ai/docs/reference/dedicated-endpoints/list-endpoint-deployments GET /v1/endpoints/{dedicated_endpoint_id}/deployments An endpoint's deployments The live deployments of the endpoint, oldest first, each with its status, traffic weight and replica counts. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.listDeployments(…) Python: client.dedicated_endpoints.list_deployments(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/deployments" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.dedicatedEndpoints.listDeployments('ded_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.dedicated_endpoints.list_deployments("ded_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api dedicatedEndpoints.listDeployments ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Add a deployment (other weights, engine or hardware). It starts with no traffic; give it a share with the traffic split. URL: https://hayonix.ai/docs/reference/dedicated-endpoints/create-endpoint-deployment POST /v1/endpoints/{dedicated_endpoint_id}/deployments Add a deployment (other weights, engine or hardware). It starts with no traffic; give it a share with the traffic split. The model must be of the same type as the endpoint, and an endpoint has at most 4 deployments. While the endpoint runs, the new deployment keeps at least `min_replicas` replicas running, billed once ready, even with no traffic. Authentication: 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). TypeScript: client.dedicatedEndpoints.createDeployment(…) Python: client.dedicated_endpoints.create_deployment(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Request body (JSON): - name (required): Its name - model (required): Model ID (`publisher/name`) - hardware (required) - region: Region code - engine - engine_options - disk_gb: Room for the weights (default 10 on CPU, 200 on GPU) - min_replicas: Default 1 - max_replicas: Default 1 - autoscaling Response: 201 EndpointDeployment Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/deployments" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "candidate", "model": "qwen/qwen2.5-0.5b-instruct", "hardware": { "sku": "cpu-2c-4gb" } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.createDeployment('ded_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'candidate', model: 'qwen/qwen2.5-0.5b-instruct', hardware: { sku: 'cpu-2c-4gb' }, }); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.create_deployment( "ded_01jc5zq4m8k3v6x9t2w7r0b1e4", name="candidate", model="qwen/qwen2.5-0.5b-instruct", hardware={"sku": "cpu-2c-4gb"}, ) print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.createDeployment \ ded_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"name":"candidate","model":"qwen/qwen2.5-0.5b-instruct","hardware":{"sku":"cpu-2c-4gb"}}' ``` ### Get a deployment URL: https://hayonix.ai/docs/reference/dedicated-endpoints/get-endpoint-deployment GET /v1/endpoint-deployments/{deployment_id} Get a deployment The deployment with its status, traffic weight, replica counts and the reason of its last failed replica start. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.getDeployment(…) Python: client.dedicated_endpoints.get_deployment(…) Path parameters: - deployment_id (required): ID of the deployment Response: 200 EndpointDeployment Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoint-deployments/dpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.getDeployment('dpl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.get_deployment("dpl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.getDeployment dpl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Change replica bounds or the autoscaling target (replicas are not recreated) URL: https://hayonix.ai/docs/reference/dedicated-endpoints/update-endpoint-deployment PATCH /v1/endpoint-deployments/{deployment_id} Change replica bounds or the autoscaling target (replicas are not recreated) Only the fields you send change; the autoscaler applies the new bounds and target to the existing replicas. An update also clears a `failed` deployment, so it tries to start replicas again. Authentication: 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). TypeScript: client.dedicatedEndpoints.updateDeployment(…) Python: client.dedicated_endpoints.update_deployment(…) Path parameters: - deployment_id (required): ID of the deployment Request body (JSON): - min_replicas: Fewest replicas kept running while the endpoint runs - max_replicas: Most replicas the autoscaler may run - autoscaling Response: 200 EndpointDeployment Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/endpoint-deployments/dpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "max_replicas": 3 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.updateDeployment('dpl_01jc5zq4m8k3v6x9t2w7r0b1e4', { max_replicas: 3 }); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.update_deployment( "dpl_01jc5zq4m8k3v6x9t2w7r0b1e4", max_replicas=3, ) print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.updateDeployment \ dpl_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"max_replicas":3}' ``` ### Delete a deployment that carries no traffic; its replicas are removed URL: https://hayonix.ai/docs/reference/dedicated-endpoints/delete-endpoint-deployment DELETE /v1/endpoint-deployments/{deployment_id} Delete a deployment that carries no traffic; its replicas are removed Refused with a conflict while the deployment has a traffic weight above 0: move its share to another deployment with the traffic split first. Its replicas are drained and removed. Authentication: 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). TypeScript: client.dedicatedEndpoints.deleteDeployment(…) Python: client.dedicated_endpoints.delete_deployment(…) Path parameters: - deployment_id (required): ID of the deployment Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/endpoint-deployments/dpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.deleteDeployment('dpl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.delete_deployment("dpl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.deleteDeployment dpl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Set the share of requests each deployment receives (weights sum to 100) URL: https://hayonix.ai/docs/reference/dedicated-endpoints/set-endpoint-traffic-split PUT /v1/endpoints/{dedicated_endpoint_id}/traffic Set the share of requests each deployment receives (weights sum to 100) 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. Authentication: 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). TypeScript: client.dedicatedEndpoints.setTrafficSplit(…) Python: client.dedicated_endpoints.set_traffic_split(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Request body (JSON): - deployments (required): Each deployment of the endpoint at most once; deployments not listed get weight 0 Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash 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 } ] }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.setTrafficSplit('ded_01jc5zq4m8k3v6x9t2w7r0b1e4', { deployments: [ { deployment_id: 'dpl_01jc5zq4m8k3v6x9t2w7r0b1e4', weight: 50, }, { deployment_id: 'dpl_01jc5zq4m8k3v6x9t2w7r0b1e5', weight: 50, }, ], }); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.set_traffic_split( "ded_01jc5zq4m8k3v6x9t2w7r0b1e4", deployments=[ { "deployment_id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e4", "weight": 50, }, { "deployment_id": "dpl_01jc5zq4m8k3v6x9t2w7r0b1e5", "weight": 50, }, ], ) print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.setTrafficSplit \ ded_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"deployments":[{"deployment_id":"dpl_01jc5zq4m8k3v6x9t2w7r0b1e4","weight":50},{"deployment_id":"dpl_01jc5zq4m8k3v6x9t2w7r0b1e5","weight":50}]}' ``` ### An endpoint's replicas, newest first URL: https://hayonix.ai/docs/reference/dedicated-endpoints/list-endpoint-replicas GET /v1/endpoints/{dedicated_endpoint_id}/replicas An endpoint's replicas, newest first Live replicas by default; pass `live=false` to include removed ones with their termination reason (at most the 200 most recent). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.listReplicas(…) Python: client.dedicated_endpoints.list_replicas(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - live: Only replicas not terminated (default true) Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/replicas" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.dedicatedEndpoints.listReplicas('ded_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.dedicated_endpoints.list_replicas("ded_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api dedicatedEndpoints.listReplicas ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### What happened to an endpoint, newest first URL: https://hayonix.ai/docs/reference/dedicated-endpoints/list-endpoint-events GET /v1/endpoints/{dedicated_endpoint_id}/events What happened to an endpoint, newest first A history of changes to the endpoint, its deployments and replicas: starts and stops (including automatic ones), traffic changes, replicas starting, becoming ready, failing or being removed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.listEvents(…) Python: client.dedicated_endpoints.list_events(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/events" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.dedicatedEndpoints.listEvents('ded_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.dedicated_endpoints.list_events("ded_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api dedicatedEndpoints.listEvents ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Requests, errors, tokens, latency and billed replica time, by deployment and over time URL: https://hayonix.ai/docs/reference/dedicated-endpoints/get-endpoint-analytics GET /v1/endpoints/{dedicated_endpoint_id}/analytics Requests, errors, tokens, latency and billed replica time, by deployment and over time Covers the last 24 hours in hourly buckets by default (the last hour for `minute`, the last 30 days for `day`), ending at the next bucket boundary. At most 2000 buckets per call. `replica_cost` is exactly what was charged for replica time in the period. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.getAnalytics(…) Python: client.dedicated_endpoints.get_analytics(…) Path parameters: - dedicated_endpoint_id (required): ID of the dedicated endpoint Query parameters: - start: Default: 24 hours before end - end: Default: now - bucket: Default hour Response: 200 EndpointAnalytics Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoints/ded_01jc5zq4m8k3v6x9t2w7r0b1e4/analytics" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const endpoint = await client.dedicatedEndpoints.getAnalytics('ded_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(endpoint); ``` Python: ```python from hayonix import Client client = Client() endpoint = client.dedicated_endpoints.get_analytics("ded_01jc5zq4m8k3v6x9t2w7r0b1e4") print(endpoint) ``` CLI: ```bash hayonix api dedicatedEndpoints.getAnalytics ded_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Public catalog models a dedicated endpoint can serve, with the engine used on CPU and on GPU hardware URL: https://hayonix.ai/docs/reference/dedicated-endpoints/list-deployable-models GET /v1/endpoint-models Public catalog models a dedicated endpoint can serve, with the engine used on CPU and on GPU hardware Available public chat, completion, embedding and rerank models whose weights can be deployed. Pass a listed `model` as a deployment's `model`; to serve other weights, use a Hugging Face source instead. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `dedicated_endpoint:read` permission (a key's scope, or a role that includes it). TypeScript: client.dedicatedEndpoints.listDeployableModels(…) Python: client.dedicated_endpoints.list_deployable_models(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/endpoint-models" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.dedicatedEndpoints.listDeployableModels()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.dedicated_endpoints.list_deployable_models(): print(item) ``` CLI: ```bash hayonix api dedicatedEndpoints.listDeployableModels ``` --- ## Files ### List files in the project URL: https://hayonix.ai/docs/reference/files/list-files GET /v1/files List files in the project Newest first by default. Includes files the platform writes, such as batch output and evaluation results; filter with `purpose`. Page with `cursor`, or with `after` as the official SDKs do. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:read` permission (a key's scope, or a role that includes it). TypeScript: client.files.list(…) Python: client.files.list(…) Query parameters: - purpose: Only files with this purpose - limit: 1–200 per page, default 50 - order: By upload time; default desc - cursor: `next_cursor` of the previous page - after: A file ID: the page after it (OpenAI-style pagination) Response: 200 FileList Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/files" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.files.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.files.list(): print(item) ``` CLI: ```bash hayonix api files.list ``` ### Upload a file (multipart form: file, purpose); validated asynchronously URL: https://hayonix.ai/docs/reference/files/upload-file POST /v1/files Upload a file (multipart form: file, purpose); validated asynchronously Streams the `file` part to storage. `Idempotency-Key` applies to the stored content: a retry with the same key, purpose, filename and bytes returns the original file. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:create` permission (a key's scope, or a role that includes it). TypeScript: client.files.upload(…) Python: client.files.upload(…) Request body (multipart form): - file (required): The file (JSON Lines; an evaluation dataset may also be CSV) - purpose (required): `fine-tune` (training or validation data), `batch` (batch requests) or `evaluation` (an evaluation dataset) Response: 201 File Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/files" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "file=@data.jsonl" \ -F "purpose=fine-tune" ``` TypeScript: ```typescript import { Client } from 'hayonix'; import { fileFromPath } from 'hayonix/node'; const client = new Client(); const file = await client.files.upload({ file: await fileFromPath('data.jsonl'), purpose: 'fine-tune' }); console.log(file); ``` Python: ```python import pathlib from hayonix import Client client = Client() file = client.files.upload(file=pathlib.Path("data.jsonl"), purpose="fine-tune") print(file) ``` CLI: ```bash hayonix api files.upload --param file=@data.jsonl --param purpose=fine-tune ``` ### The upload size cap, the purposes and the validation limits URL: https://hayonix.ai/docs/reference/files/get-file-limits GET /v1/files/limits The upload size cap, the purposes and the validation limits Read this before uploading to check a file against the limits in force; larger files and longer lines are refused or fail validation. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:read` permission (a key's scope, or a role that includes it). TypeScript: client.files.getLimits(…) Python: client.files.get_limits(…) Response: 200 FileLimits Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/files/limits" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const file = await client.files.getLimits(); console.log(file); ``` Python: ```python from hayonix import Client client = Client() file = client.files.get_limits() print(file) ``` CLI: ```bash hayonix api files.getLimits ``` ### Get a file, with its validation state and report URL: https://hayonix.ai/docs/reference/files/get-file GET /v1/files/{file_id} Get a file, with its validation state and report Poll this after an upload until `validation.state` is `valid` or `invalid`; small files are usually validated within seconds of upload. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:read` permission (a key's scope, or a role that includes it). TypeScript: client.files.get(…) Python: client.files.get(…) Path parameters: - file_id (required): ID of the file Response: 200 File Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/files/file_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const file = await client.files.get('file_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(file); ``` Python: ```python from hayonix import Client client = Client() file = client.files.get("file_01jc5zq4m8k3v6x9t2w7r0b1e4") print(file) ``` CLI: ```bash hayonix api files.get file_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Delete a file URL: https://hayonix.ai/docs/reference/files/delete-file DELETE /v1/files/{file_id} Delete a file Removes the file and its content for good. Refused with `file_in_use` while a fine-tuning job, batch or evaluation that has not ended reads it. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:delete` permission (a key's scope, or a role that includes it). TypeScript: client.files.delete(…) Python: client.files.delete(…) Path parameters: - file_id (required): ID of the file Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/files/file_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const file = await client.files.delete('file_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(file); ``` Python: ```python from hayonix import Client client = Client() file = client.files.delete("file_01jc5zq4m8k3v6x9t2w7r0b1e4") print(file) ``` CLI: ```bash hayonix api files.delete file_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Download a file's content URL: https://hayonix.ai/docs/reference/files/get-file-content GET /v1/files/{file_id}/content Download a file's content Streams the stored bytes as an attachment under the original filename. Where a request cannot carry credentials, create a download link instead. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:read` permission (a key's scope, or a role that includes it). TypeScript: client.files.getContent(…) Python: client.files.get_content(…) Path parameters: - file_id (required): ID of the file Response: 200 the file content (application/octet-stream) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/files/file_01jc5zq4m8k3v6x9t2w7r0b1e4/content" \ -H "Authorization: Bearer $API_KEY" \ -o output.bin ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const download = await client.files.getContent('file_01jc5zq4m8k3v6x9t2w7r0b1e4'); await download.saveTo(download.filename ?? 'output.bin'); ``` Python: ```python from hayonix import Client client = Client() download = client.files.get_content("file_01jc5zq4m8k3v6x9t2w7r0b1e4") download.save(download.filename or "output.bin") ``` CLI: ```bash hayonix api files.getContent file_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A short-lived link to download a file's content without credentials URL: https://hayonix.ai/docs/reference/files/create-file-download-link POST /v1/files/{file_id}/download-link A short-lived link to download a file's content without credentials The link works for 5 minutes, for this file only, and stops working if the file is deleted. Use it where a request cannot carry credentials (a browser saving a large file straight to disk). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `file:read` permission (a key's scope, or a role that includes it). TypeScript: client.files.createDownloadLink(…) Python: client.files.create_download_link(…) Path parameters: - file_id (required): ID of the file Response: 201 DownloadLink Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/files/file_01jc5zq4m8k3v6x9t2w7r0b1e4/download-link" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const file = await client.files.createDownloadLink('file_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(file); ``` Python: ```python from hayonix import Client client = Client() file = client.files.create_download_link("file_01jc5zq4m8k3v6x9t2w7r0b1e4") print(file) ``` CLI: ```bash hayonix api files.createDownloadLink file_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Download through a signed link (no credentials: the token is the credential) URL: https://hayonix.ai/docs/reference/files/download-with-link GET /v1/downloads Download through a signed link (no credentials: the token is the credential) Answers 404 `download_link_invalid` for a token that is not genuine, 404 `download_link_expired` once it has expired, and 404 `not_found` when the object is gone. Authentication: None: this operation is public. TypeScript: client.files.downloadWithLink(…) Python: client.files.download_with_link(…) Query parameters: - token (required): From a download link Response: 200 the file content (application/octet-stream) Errors: - 400 invalid_request_error: A parameter or body field is missing or not allowed; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/downloads?token=%3Ctoken%3E" \ -H "Authorization: Bearer $API_KEY" \ -o output.bin ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const download = await client.files.downloadWithLink({ token: '' }); await download.saveTo(download.filename ?? 'output.bin'); ``` Python: ```python from hayonix import Client client = Client() download = client.files.download_with_link(token="") download.save(download.filename or "output.bin") ``` CLI: ```bash hayonix api files.downloadWithLink --param token='' ``` --- ## Fine-tuning ### Models that can be fine-tuned, how, on which hardware and at what price URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tune-base-models GET /v1/fine-tunes/base-models Models that can be fine-tuned, how, on which hardware and at what price Every base model accepted as `model` when creating a job, with the methods and adapter types it supports and its per-token training price from the price book in force. The list is returned whole, in one page. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.listBaseModels(…) Python: client.fine_tuning.list_base_models(…) Response: 200 JSON Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/base-models" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.listBaseModels(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.list_base_models() print(result) ``` CLI: ```bash hayonix api fineTuning.listBaseModels ``` ### Price estimate for fine-tuning on a validated dataset URL: https://hayonix.ai/docs/reference/fine-tuning/estimate-fine-tune GET /v1/fine-tunes/estimate Price estimate for fine-tuning on a validated dataset Checks the model, files and settings as creating a job would, and returns the estimated billable tokens, their cost and the credit a job would reserve. Nothing is created or charged; the files must have finished validation. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.estimate(…) Python: client.fine_tuning.estimate(…) Query parameters: - model (required): A fine-tunable base model: slug or ID - training_file_id (required): ID of the training file - validation_file_id: ID of the validation file - method: Training method (default supervised) - adapter: Adapter type (default lora) - epochs: Passes over the training file (default 1) - evals_per_epoch: Evaluations of the validation file per epoch (default 1) - sku: Hardware SKU the job would train on (default: the base model's first listed SKU); checked, but it does not change the price Response: 200 FineTuneEstimate Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/estimate?model=%3Cmodel%3E&training_file_id=file_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.estimate({ model: '', training_file_id: 'file_01jc5zq4m8k3v6x9t2w7r0b1e4', }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.estimate( model="", training_file_id="file_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(result) ``` CLI: ```bash hayonix api fineTuning.estimate \ --param model='' \ --param training_file_id='file_01jc5zq4m8k3v6x9t2w7r0b1e4' ``` ### List fine-tuning jobs, newest first URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tunes GET /v1/fine-tunes List fine-tuning jobs, newest first The project's jobs with their progress, billing and, for succeeded jobs, the resulting model. Filter with `state`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.list(…) Python: client.fine_tuning.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - state: Only jobs in this state Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.fineTuning.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.fine_tuning.list(): print(item) ``` CLI: ```bash hayonix api fineTuning.list ``` ### Create a fine-tuning job (reserves its estimated cost; 402 when credit is short) URL: https://hayonix.ai/docs/reference/fine-tuning/create-fine-tune POST /v1/fine-tunes Create a fine-tuning job (reserves its estimated cost; 402 when credit is short) The job is billed per training and evaluation token, never for the hardware. Just before training starts the exact token count replaces the estimate and the reserved credit is resized to it; if the credit cannot cover it the job stops with `insufficient_credit` and nothing is charged. A succeeded job produces a fine-tuned model. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:create` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.create(…) Python: client.fine_tuning.create(…) Request body (JSON): - model (required): A fine-tunable base model (GET /v1/fine-tunes/base-models): slug or ID - training_file_id (required): ID of the training file - validation_file_id: ID of the validation file - method: Default supervised - adapter: Default LoRA - hyperparameters - evaluation: Evaluations per epoch on the validation file (default 1) - early_stopping: Stop when evaluation loss has not improved for `patience` evaluations - checkpoints: Checkpoints saved over the run, the final one included (default 1) - merge_weights: LoRA: also produce merged full weights (default true) - continue_from_checkpoint_id: Continue training from a checkpoint of an earlier job - suffix: Lowercase letters, digits and dashes; part of the result model name - hardware: Where the job trains: `sku` (default: the base model's first listed SKU) and, for a GPU SKU, `gpu_count` (1–8, default 1; 0 for a CPU SKU). Training is billed per token whatever the hardware. - integrations Response: 201 FineTune Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "model": "HuggingFaceTB/SmolLM2-135M-Instruct", "training_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4", "method": { "type": "supervised" }, "adapter": { "type": "lora", "rank": 8 }, "hyperparameters": { "epochs": 2, "learning_rate": 0.0002 } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.create({ model: 'HuggingFaceTB/SmolLM2-135M-Instruct', training_file_id: 'file_01jc5zq4m8k3v6x9t2w7r0b1e4', method: { type: 'supervised' }, adapter: { type: 'lora', rank: 8 }, hyperparameters: { epochs: 2, learning_rate: 0.0002 }, }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.create( model="HuggingFaceTB/SmolLM2-135M-Instruct", training_file_id="file_01jc5zq4m8k3v6x9t2w7r0b1e4", method={"type": "supervised"}, adapter={"type": "lora", "rank": 8}, hyperparameters={"epochs": 2, "learning_rate": 0.0002}, ) print(result) ``` CLI: ```bash hayonix api fineTuning.create \ --body '{"model":"HuggingFaceTB/SmolLM2-135M-Instruct","training_file_id":"file_01jc5zq4m8k3v6x9t2w7r0b1e4","method":{"type":"supervised"},"adapter":{"type":"lora","rank":8},"hyperparameters":{"epochs":2,"learning_rate":0.0002}}' ``` ### Get a fine-tuning job URL: https://hayonix.ai/docs/reference/fine-tuning/get-fine-tune GET /v1/fine-tunes/{fine_tune_id} Get a fine-tuning job Its state, progress, cost so far and, once it has succeeded, the fine-tuned model in `result`. Poll this until the state is `succeeded`, `failed`, `cancelled` or `stopped`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.get(…) Python: client.fine_tuning.get(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Response: 200 FineTune Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.get('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.get("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.get ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Cancel a job (charged only for the tokens it trained; idempotent) URL: https://hayonix.ai/docs/reference/fine-tuning/cancel-fine-tune POST /v1/fine-tunes/{fine_tune_id}/cancel Cancel a job (charged only for the tokens it trained; idempotent) Ends the job at once and releases the rest of its reserved credit; no model is produced. Cancelling a cancelled job returns it unchanged; a job that has already ended otherwise answers 409 `job_finished`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:update` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.cancel(…) Python: client.fine_tuning.cancel(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Response: 200 FineTune Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.cancel('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.cancel("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.cancel ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A job's events, oldest first URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tune-events GET /v1/fine-tunes/{fine_tune_id}/events A job's events, oldest first The job's timeline: state changes, checkpoints, warnings and errors, from the platform and from the training run. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.listEvents(…) Python: client.fine_tuning.list_events(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/events" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.fineTuning.listEvents('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.fine_tuning.list_events("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api fineTuning.listEvents ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A job's training metrics, one point per step in step order (chart-ready) URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tune-metrics GET /v1/fine-tunes/{fine_tune_id}/metrics A job's training metrics, one point per step in step order (chart-ready) Up to 200 points per page by default. While the job trains, poll with `after_step` set to the last step you have to get only new points. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.listMetrics(…) Python: client.fine_tuning.list_metrics(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - after_step: Only points after this step (polling) Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/metrics" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.fineTuning.listMetrics('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.fine_tuning.list_metrics("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api fineTuning.listMetrics ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A job's checkpoints, oldest first URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tune-checkpoints GET /v1/fine-tunes/{fine_tune_id}/checkpoints A job's checkpoints, oldest first Weights saved during the run (as many as the `checkpoints` setting asks for, the final one included), each with its artefacts. Any checkpoint can be downloaded or used to continue training in a new job. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.listCheckpoints(…) Python: client.fine_tuning.list_checkpoints(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/checkpoints" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.fineTuning.listCheckpoints('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.fine_tuning.list_checkpoints("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api fineTuning.listCheckpoints ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Download the adapter or the merged weights of a checkpoint as a tar archive URL: https://hayonix.ai/docs/reference/fine-tuning/download-fine-tune GET /v1/fine-tunes/{fine_tune_id}/download Download the adapter or the merged weights of a checkpoint as a tar archive Streams one artefact of the final checkpoint, or of `checkpoint_id`. Answers 400 `artifact_unavailable` when the checkpoint lacks it (a full fine-tune has no adapter). Where a request cannot carry credentials, create a download link instead. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.download(…) Python: client.fine_tuning.download(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Query parameters: - artifact: `adapter` (LoRA, default for LoRA jobs), `merged` (full weights, default for full fine-tunes), or a serving format: `adapter_gguf`, `merged_gguf` - checkpoint_id: Default: the final checkpoint Response: 200 the file content (application/x-tar) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/download" \ -H "Authorization: Bearer $API_KEY" \ -o output.bin ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const download = await client.fineTuning.download('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4'); await download.saveTo(download.filename ?? 'output.bin'); ``` Python: ```python from hayonix import Client client = Client() download = client.fine_tuning.download("ftj_01jc5zq4m8k3v6x9t2w7r0b1e4") download.save(download.filename or "output.bin") ``` CLI: ```bash hayonix api fineTuning.download ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A short-lived link to download an artefact tar without credentials URL: https://hayonix.ai/docs/reference/fine-tuning/create-fine-tune-download-link POST /v1/fine-tunes/{fine_tune_id}/download-link A short-lived link to download an artefact tar without credentials Takes the same `artifact` and `checkpoint_id` as `GET /v1/fine-tunes/{fine_tune_id}/download` (the body may be omitted for the defaults). The link works for 5 minutes for that one archive, which is streamed: use it where a request cannot carry credentials (a browser saving large weights to disk). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.createDownloadLink(…) Python: client.fine_tuning.create_download_link(…) Path parameters: - fine_tune_id (required): ID of the fine-tuning job Request body (JSON): - artifact: As for the download route (default: adapter for LoRA jobs) - checkpoint_id: Default: the final checkpoint Response: 201 DownloadLink Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tunes/ftj_01jc5zq4m8k3v6x9t2w7r0b1e4/download-link" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "artifact": "adapter" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.createDownloadLink('ftj_01jc5zq4m8k3v6x9t2w7r0b1e4', { artifact: 'adapter' }); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.create_download_link( "ftj_01jc5zq4m8k3v6x9t2w7r0b1e4", artifact="adapter", ) print(result) ``` CLI: ```bash hayonix api fineTuning.createDownloadLink \ ftj_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"artifact":"adapter"}' ``` ### The project's fine-tuned models (results of succeeded jobs), newest first URL: https://hayonix.ai/docs/reference/fine-tuning/list-fine-tuned-models GET /v1/fine-tuned-models The project's fine-tuned models (results of succeeded jobs), newest first Deleted models are left out. Each model shows its artefacts and how it can be served (per token on a shared pool, or on a dedicated endpoint). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.listModels(…) Python: client.fine_tuning.list_models(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tuned-models" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.fineTuning.listModels()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.fine_tuning.list_models(): print(item) ``` CLI: ```bash hayonix api fineTuning.listModels ``` ### Get a fine-tuned model of the project URL: https://hayonix.ai/docs/reference/fine-tuning/get-fine-tuned-model GET /v1/fine-tuned-models/{fine_tuned_model_id} Get a fine-tuned model of the project Its artefacts, the job and checkpoint it came from, and its serving status: poll `serving.shared.status` after enabling it until it is `ready`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:read` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.getModel(…) Python: client.fine_tuning.get_model(…) Path parameters: - fine_tuned_model_id (required): ID of the fine-tuned model Response: 200 FineTunedModel Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/fine-tuned-models/ftm_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.getModel('ftm_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.get_model("ftm_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.getModel ftm_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Delete a fine-tuned model (refused with 409 while it is served) URL: https://hayonix.ai/docs/reference/fine-tuning/delete-fine-tuned-model DELETE /v1/fine-tuned-models/{fine_tuned_model_id} Delete a fine-tuned model (refused with 409 while it is served) Refused while shared serving is enabled, while shared replicas still hold its adapter, or while a dedicated endpoint deployment serves it. Its name is freed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:delete` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.deleteModel(…) Python: client.fine_tuning.delete_model(…) Path parameters: - fine_tuned_model_id (required): ID of the fine-tuned model Response: 200 FineTunedModel Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/fine-tuned-models/ftm_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.deleteModel('ftm_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.delete_model("ftm_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.deleteModel ftm_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Serve a LoRA fine-tune per token on the shared pool of its base model (idempotent) URL: https://hayonix.ai/docs/reference/fine-tuning/enable-fine-tuned-model POST /v1/fine-tuned-models/{fine_tuned_model_id}/enable Serve a LoRA fine-tune per token on the shared pool of its base model (idempotent) Needs a shared pool for the base model that accepts adapters and a price for fine-tuned inference on that base. The model is `loading` until a pool replica has loaded the adapter, then `ready`: its `name` is callable with this project's keys. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:update` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.enableModel(…) Python: client.fine_tuning.enable_model(…) Path parameters: - fine_tuned_model_id (required): ID of the fine-tuned model Response: 200 FineTunedModel Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/fine-tuned-models/ftm_01jc5zq4m8k3v6x9t2w7r0b1e4/enable" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.enableModel('ftm_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.enable_model("ftm_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.enableModel ftm_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Stop serving a fine-tune per token (idempotent) URL: https://hayonix.ai/docs/reference/fine-tuning/disable-fine-tuned-model POST /v1/fine-tuned-models/{fine_tuned_model_id}/disable Stop serving a fine-tune per token (idempotent) The model ID stops resolving as soon as this returns (new requests get the unknown-model error); requests already running finish and are billed as usual. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `fine_tune_job:update` permission (a key's scope, or a role that includes it). TypeScript: client.fineTuning.disableModel(…) Python: client.fine_tuning.disable_model(…) Path parameters: - fine_tuned_model_id (required): ID of the fine-tuned model Response: 200 FineTunedModel Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/fine-tuned-models/ftm_01jc5zq4m8k3v6x9t2w7r0b1e4/disable" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.fineTuning.disableModel('ftm_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.fine_tuning.disable_model("ftm_01jc5zq4m8k3v6x9t2w7r0b1e4") print(result) ``` CLI: ```bash hayonix api fineTuning.disableModel ftm_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Batches ### List batches in the project, newest first URL: https://hayonix.ai/docs/reference/batches/list-batches GET /v1/batches List batches in the project, newest first Every batch, whatever its status. Page with `cursor`, or with `after` as the official SDKs do. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `batch:read` permission (a key's scope, or a role that includes it). TypeScript: client.batches.list(…) Python: client.batches.list(…) Query parameters: - limit: 1–200 per page, default 20 - cursor: `next_cursor` of the previous page - after: A batch ID: the page after it (OpenAI-style pagination) Response: 200 BatchList Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/batches" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.batches.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.batches.list(): print(item) ``` CLI: ```bash hayonix api batches.list ``` ### Create a batch from an uploaded file of requests (validated and run asynchronously) URL: https://hayonix.ai/docs/reference/batches/create-batch POST /v1/batches Create a batch from an uploaded file of requests (validated and run asynchronously) Each line of the input file is `{"custom_id", "method": "POST", "url", "body"}`, with `url` equal to `endpoint`. Requests are charged per token at batch prices as they complete; credit is reserved per request as for live inference, so a batch stops (with partial results) when credit runs out. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `batch:create` permission (a key's scope, or a role that includes it). TypeScript: client.batches.create(…) Python: client.batches.create(…) Request body (JSON): - input_file_id (required): A file uploaded with purpose `batch` - endpoint (required): The route every request goes to: /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/responses - completion_window (required): Time allowed to run every request: 24h - metadata: Up to 16 string pairs (keys ≤ 64, values ≤ 512 characters) - output_expires_after: How long the output and error files are kept after they are written (3600–2592000 s; default 2592000 s) Response: 201 Batch Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/batches" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "input_file_id": "file_01jz8x3y4z5a6b7c8d9e0f1g2h", "endpoint": "/v1/chat/completions", "completion_window": "24h" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const batche = await client.batches.create({ input_file_id: 'file_01jz8x3y4z5a6b7c8d9e0f1g2h', endpoint: '/v1/chat/completions', completion_window: '24h', }); console.log(batche); ``` Python: ```python from hayonix import Client client = Client() batche = client.batches.create( input_file_id="file_01jz8x3y4z5a6b7c8d9e0f1g2h", endpoint="/v1/chat/completions", completion_window="24h", ) print(batche) ``` CLI: ```bash hayonix api batches.create \ --body '{"input_file_id":"file_01jz8x3y4z5a6b7c8d9e0f1g2h","endpoint":"/v1/chat/completions","completion_window":"24h"}' ``` ### Get a batch: status, request counts, stage times, cost so far URL: https://hayonix.ai/docs/reference/batches/get-batch GET /v1/batches/{batch_id} Get a batch: status, request counts, stage times, cost so far Poll this until the status is `completed`, `expired`, `failed` or `cancelled`, then download `output_file_id` and `error_file_id` through the files API. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `batch:read` permission (a key's scope, or a role that includes it). TypeScript: client.batches.get(…) Python: client.batches.get(…) Path parameters: - batch_id (required): ID of the batch Response: 200 Batch Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/batches/bat_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const batche = await client.batches.get('bat_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(batche); ``` Python: ```python from hayonix import Client client = Client() batche = client.batches.get("bat_01jc5zq4m8k3v6x9t2w7r0b1e4") print(batche) ``` CLI: ```bash hayonix api batches.get bat_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### List the lines of a batch in input order: status, error, tokens and cost URL: https://hayonix.ai/docs/reference/batches/list-batch-lines GET /v1/batches/{batch_id}/lines List the lines of a batch in input order: status, error, tokens and cost One entry per request line of the input file, in line order, once the batch is validated. Use it to follow a batch line by line, or to find the lines that failed (`status=failed`) without downloading the error file. Response bodies are in the output file. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `batch:read` permission (a key's scope, or a role that includes it). TypeScript: client.batches.listLines(…) Python: client.batches.list_lines(…) Path parameters: - batch_id (required): ID of the batch Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - status: Only lines in this status (default: every line) Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/batches/bat_01jc5zq4m8k3v6x9t2w7r0b1e4/lines" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.batches.listLines('bat_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.batches.list_lines("bat_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api batches.listLines bat_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Cancel a batch (requests in flight may finish; completed ones are kept and charged) URL: https://hayonix.ai/docs/reference/batches/cancel-batch POST /v1/batches/{batch_id}/cancel Cancel a batch (requests in flight may finish; completed ones are kept and charged) No new request starts. The batch moves to `cancelling`, then to `cancelled` once its partial result files are written; requests never run are listed in the error file and not charged. Cancelling again returns the batch unchanged; a batch that has already ended answers 409 `batch_not_cancellable`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `batch:update` permission (a key's scope, or a role that includes it). TypeScript: client.batches.cancel(…) Python: client.batches.cancel(…) Path parameters: - batch_id (required): ID of the batch Response: 200 Batch Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/batches/bat_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const batche = await client.batches.cancel('bat_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(batche); ``` Python: ```python from hayonix import Client client = Client() batche = client.batches.cancel("bat_01jc5zq4m8k3v6x9t2w7r0b1e4") print(batche) ``` CLI: ```bash hayonix api batches.cancel bat_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Evaluations ### List the models this project can use as a judge or to generate candidates URL: https://hayonix.ai/docs/reference/evaluations/list-evaluation-models GET /v1/evaluations/models List the models this project can use as a judge or to generate candidates Chat models the project can call that have batch prices (every evaluation call is charged at batch prices), the project’s fine-tuned models, and its dedicated endpoints’ models (paid by replica time). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:read` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.listModels(…) Python: client.evaluations.list_models(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 EvaluationModelList Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations/models" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.evaluations.listModels()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.evaluations.list_models(): print(item) ``` CLI: ```bash hayonix api evaluations.listModels ``` ### Estimate an evaluation: the most it can cost, and its first row’s requests URL: https://hayonix.ai/docs/reference/evaluations/estimate-evaluation POST /v1/evaluations/estimate Estimate an evaluation: the most it can cost, and its first row’s requests Takes the same body as creating an evaluation and checks it the same way (the dataset must be validated). Nothing is created or charged. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:read` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.estimate(…) Python: client.evaluations.estimate(…) Request body (JSON): - name: Its name - mode (required): `label`: one label per row from `label.choices`; `grade`: a number from `grade.min` to `grade.max`; `pairwise`: the better of `pairwise.a` and `pairwise.b` (judged in both orders). - dataset_file_id (required): A file uploaded with purpose `evaluation` (JSONL, or CSV with a header) - judge (required) - target: Modes `label` and `grade` - pairwise: Mode `pairwise`: the two candidates - label: Mode `label` - grade: Mode `grade` (whole-number bounds ask for whole-number scores) Response: 200 EvaluationEstimate Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations/estimate" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "label", "dataset_file_id": "file_01jz8x3y4z5a6b7c8d9e0f1g2h", "judge": { "model": "qwen/qwen2.5-0.5b-instruct", "instructions": "Classify the sentiment of this customer review." }, "target": { "column": "review" }, "label": { "choices": [ "positive", "negative", "neutral" ], "passing": [ "positive" ] } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const evaluation = await client.evaluations.estimate({ mode: 'label', dataset_file_id: 'file_01jz8x3y4z5a6b7c8d9e0f1g2h', judge: { model: 'qwen/qwen2.5-0.5b-instruct', instructions: 'Classify the sentiment of this customer review.', }, target: { column: 'review' }, label: { choices: ['positive', 'negative', 'neutral'], passing: ['positive'], }, }); console.log(evaluation); ``` Python: ```python from hayonix import Client client = Client() evaluation = client.evaluations.estimate( mode="label", dataset_file_id="file_01jz8x3y4z5a6b7c8d9e0f1g2h", judge={ "model": "qwen/qwen2.5-0.5b-instruct", "instructions": "Classify the sentiment of this customer review.", }, target={"column": "review"}, label={ "choices": ["positive", "negative", "neutral"], "passing": ["positive"], }, ) print(evaluation) ``` CLI: ```bash hayonix api evaluations.estimate \ --body '{"mode":"label","dataset_file_id":"file_01jz8x3y4z5a6b7c8d9e0f1g2h","judge":{"model":"qwen/qwen2.5-0.5b-instruct","instructions":"Classify the sentiment of this customer review."},"target":{"column":"review"},"label":{"choices":["positive","negative","neutral"],"passing":["positive"]}}' ``` ### List evaluations in the project, newest first URL: https://hayonix.ai/docs/reference/evaluations/list-evaluations GET /v1/evaluations List evaluations in the project, newest first Each evaluation carries its results: final once it has ended, computed from the rows finished so far while it runs. Filter with `status`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:read` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.list(…) Python: client.evaluations.list(…) Query parameters: - limit: 1–200, default 20 - cursor: `next_cursor` of the previous page - status: Only evaluations in this status Response: 200 EvaluationList Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.evaluations.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.evaluations.list(): print(item) ``` CLI: ```bash hayonix api evaluations.list ``` ### Create an evaluation over an uploaded dataset (validated and run asynchronously) URL: https://hayonix.ai/docs/reference/evaluations/create-evaluation POST /v1/evaluations Create an evaluation over an uploaded dataset (validated and run asynchronously) Every model call (generating a candidate, each judging pass) is charged as it completes at the models’ batch prices; nothing is reserved up front. When credit runs out the evaluation stops and keeps every row it finished. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:create` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.create(…) Python: client.evaluations.create(…) Request body (JSON): - name: Its name - mode (required): `label`: one label per row from `label.choices`; `grade`: a number from `grade.min` to `grade.max`; `pairwise`: the better of `pairwise.a` and `pairwise.b` (judged in both orders). - dataset_file_id (required): A file uploaded with purpose `evaluation` (JSONL, or CSV with a header) - judge (required) - target: Modes `label` and `grade` - pairwise: Mode `pairwise`: the two candidates - label: Mode `label` - grade: Mode `grade` (whole-number bounds ask for whole-number scores) Response: 201 Evaluation Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "mode": "label", "dataset_file_id": "file_01jz8x3y4z5a6b7c8d9e0f1g2h", "judge": { "model": "qwen/qwen2.5-0.5b-instruct", "instructions": "Classify the sentiment of this customer review." }, "target": { "column": "review" }, "label": { "choices": [ "positive", "negative", "neutral" ], "passing": [ "positive" ] } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const evaluation = await client.evaluations.create({ mode: 'label', dataset_file_id: 'file_01jz8x3y4z5a6b7c8d9e0f1g2h', judge: { model: 'qwen/qwen2.5-0.5b-instruct', instructions: 'Classify the sentiment of this customer review.', }, target: { column: 'review' }, label: { choices: ['positive', 'negative', 'neutral'], passing: ['positive'], }, }); console.log(evaluation); ``` Python: ```python from hayonix import Client client = Client() evaluation = client.evaluations.create( mode="label", dataset_file_id="file_01jz8x3y4z5a6b7c8d9e0f1g2h", judge={ "model": "qwen/qwen2.5-0.5b-instruct", "instructions": "Classify the sentiment of this customer review.", }, target={"column": "review"}, label={ "choices": ["positive", "negative", "neutral"], "passing": ["positive"], }, ) print(evaluation) ``` CLI: ```bash hayonix api evaluations.create \ --body '{"mode":"label","dataset_file_id":"file_01jz8x3y4z5a6b7c8d9e0f1g2h","judge":{"model":"qwen/qwen2.5-0.5b-instruct","instructions":"Classify the sentiment of this customer review."},"target":{"column":"review"},"label":{"choices":["positive","negative","neutral"],"passing":["positive"]}}' ``` ### Get an evaluation: status, progress, results so far, cost URL: https://hayonix.ai/docs/reference/evaluations/get-evaluation GET /v1/evaluations/{evaluation_id} Get an evaluation: status, progress, results so far, cost Poll this until the status is `completed`, `stopped`, `failed` or `cancelled`. Once the results file is written, `result_file_id` names it (one JSON line per row, downloadable through the files API). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:read` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.get(…) Python: client.evaluations.get(…) Path parameters: - evaluation_id (required): ID of the evaluation Response: 200 Evaluation Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations/evl_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const evaluation = await client.evaluations.get('evl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(evaluation); ``` Python: ```python from hayonix import Client client = Client() evaluation = client.evaluations.get("evl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(evaluation) ``` CLI: ```bash hayonix api evaluations.get evl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Cancel an evaluation (calls in flight may finish; finished rows are kept) URL: https://hayonix.ai/docs/reference/evaluations/cancel-evaluation POST /v1/evaluations/{evaluation_id}/cancel Cancel an evaluation (calls in flight may finish; finished rows are kept) No new call starts. The evaluation moves to `cancelling`, then to `cancelled` once its results file is written; unfinished rows become `skipped` and are not charged. Cancelling again returns the evaluation unchanged; one that has already ended answers 409 `evaluation_not_cancellable`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:update` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.cancel(…) Python: client.evaluations.cancel(…) Path parameters: - evaluation_id (required): ID of the evaluation Response: 200 Evaluation Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/evaluations/evl_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const evaluation = await client.evaluations.cancel('evl_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(evaluation); ``` Python: ```python from hayonix import Client client = Client() evaluation = client.evaluations.cancel("evl_01jc5zq4m8k3v6x9t2w7r0b1e4") print(evaluation) ``` CLI: ```bash hayonix api evaluations.cancel evl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### List an evaluation’s rows in dataset order: verdict, reasoning, texts, cost URL: https://hayonix.ai/docs/reference/evaluations/list-evaluation-rows GET /v1/evaluations/{evaluation_id}/rows List an evaluation’s rows in dataset order: verdict, reasoning, texts, cost Available while the evaluation runs, so finished rows can be inspected early. Use `filter` to see only passing, failing, errored or inconsistent rows. Texts are shortened here; the results file has them whole. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `evaluation:read` permission (a key's scope, or a role that includes it). TypeScript: client.evaluations.listRows(…) Python: client.evaluations.list_rows(…) Path parameters: - evaluation_id (required): ID of the evaluation Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - filter: `passed`; `failed` (judged, did not pass; pairwise: B won or tie); `errored` (errors and rows never run); `inconsistent` (pairwise passes disagreed); default `all` Response: 200 EvaluationRowList Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/evaluations/evl_01jc5zq4m8k3v6x9t2w7r0b1e4/rows" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.evaluations.listRows('evl_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.evaluations.list_rows("evl_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api evaluations.listRows evl_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` --- ## Sandboxes ### Sandbox sizes with their prices, and the limits that apply to sandboxes and runs URL: https://hayonix.ai/docs/reference/sandboxes/list-sandbox-sizes GET /v1/sandboxes/sizes Sandbox sizes with their prices, and the limits that apply to sandboxes and runs Everything needed to choose a size and stay within limits, in one response: every size with its current price, the defaults and ranges of lifetimes, idle timeouts and run settings, and the languages a run can use. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.listSizes(…) Python: client.sandboxes.list_sizes(…) Response: 200 SandboxSizes Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sizes" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.listSizes(); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.list_sizes() print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.listSizes ``` ### List sandboxes in the project, newest first (ended ones only when asked for) URL: https://hayonix.ai/docs/reference/sandboxes/list-sandboxes GET /v1/sandboxes List sandboxes in the project, newest first (ended ones only when asked for) Returns the sandboxes that have not ended, with their state, time left and cost so far; pass `include_ended=true` to list ended ones as well. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.list(…) Python: client.sandboxes.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - include_ended: Also list sandboxes that have ended (default false) Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.sandboxes.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.sandboxes.list(): print(item) ``` CLI: ```bash hayonix api sandboxes.list ``` ### Create a sandbox (launch gate and quotas apply); it ends by itself at its deadline URL: https://hayonix.ai/docs/reference/sandboxes/create-sandbox POST /v1/sandboxes Create a sandbox (launch gate and quotas apply); it ends by itself at its deadline The sandbox starts at once and is billed per second from when it starts, at its size’s price. It ends at `lifetime_seconds` (extendable), after `idle_timeout_seconds` without a run or a file operation, or when ended. Nothing in it survives its end. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:create` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.create(…) Python: client.sandboxes.create(…) Request body (JSON): - name: Its name - size: One of cpu-2c-4gb, cpu-4c-16gb, cpu-8c-32gb (default cpu-2c-4gb) - region (required): Region code - lifetime_seconds: How long it lives unless extended (default 3600) - idle_timeout_seconds: It ends after this long without a run or a file operation (default 900) - metadata: Your own key/value labels, returned as given Response: 201 Sandbox Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "agent scratch", "size": "cpu-2c-4gb", "region": "dev-local-1", "lifetime_seconds": 3600 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.create({ name: 'agent scratch', size: 'cpu-2c-4gb', region: 'dev-local-1', lifetime_seconds: 3600, }); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.create( name="agent scratch", size="cpu-2c-4gb", region="dev-local-1", lifetime_seconds=3600, ) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.create \ --body '{"name":"agent scratch","size":"cpu-2c-4gb","region":"dev-local-1","lifetime_seconds":3600}' ``` ### Get a sandbox: its state, time left and cost so far URL: https://hayonix.ai/docs/reference/sandboxes/get-sandbox GET /v1/sandboxes/{sandbox_id} Get a sandbox: its state, time left and cost so far Poll this to see when a new sandbox is `ready`, how long it has left before its deadline or idle timeout, and why it ended. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.get(…) Python: client.sandboxes.get(…) Path parameters: - sandbox_id (required): ID of the sandbox Response: 200 Sandbox Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.get('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.get("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4") print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.get sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Move its deadline later (never past its maximum lifetime) URL: https://hayonix.ai/docs/reference/sandboxes/extend-sandbox POST /v1/sandboxes/{sandbox_id}/extend Move its deadline later (never past its maximum lifetime) Adds `seconds` to the deadline (counted from now if the deadline has passed), capped at `lifetime.max_expires_at`, and counts as activity for the idle timeout. An ended sandbox answers 409 `sandbox_ended`; one already at its maximum answers 409 `lifetime_limit`. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:update` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.extend(…) Python: client.sandboxes.extend(…) Path parameters: - sandbox_id (required): ID of the sandbox Request body (JSON): - seconds (required): Added to the deadline (from now, if that is later) Response: 200 Sandbox Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/extend" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "seconds": 1800 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.extend('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', { seconds: 1800 }); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.extend("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", seconds=1800) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.extend sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"seconds":1800}' ``` ### End a sandbox now: runs are cut off, its files are deleted, billing stops URL: https://hayonix.ai/docs/reference/sandboxes/end-sandbox POST /v1/sandboxes/{sandbox_id}/end End a sandbox now: runs are cut off, its files are deleted, billing stops The sandbox cannot be restarted and nothing in it can be recovered; its run records stay readable for 7 days. Ending a sandbox that has already ended returns it unchanged. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:delete` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.end(…) Python: client.sandboxes.end(…) Path parameters: - sandbox_id (required): ID of the sandbox Response: 200 Sandbox Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/end" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.end('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.end("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4") print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.end sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Runs of a sandbox, newest first (kept until 7 days after it ends) URL: https://hayonix.ai/docs/reference/sandboxes/list-sandbox-runs GET /v1/sandboxes/{sandbox_id}/runs Runs of a sandbox, newest first (kept until 7 days after it ends) Every run with its outcome and the first 65536 bytes of each of stdout and stderr. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.listRuns(…) Python: client.sandboxes.list_runs(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.sandboxes.listRuns('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.sandboxes.list_runs("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api sandboxes.listRuns sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Run code in the sandbox and wait for the result (or stream it) URL: https://hayonix.ai/docs/reference/sandboxes/run-sandbox-code POST /v1/sandboxes/{sandbox_id}/runs Run code in the sandbox and wait for the result (or stream it) Python runs share one interpreter per sandbox, so variables, imports and functions persist between runs; JavaScript and shell runs each start a fresh process. Files in the workspace persist for the sandbox’s life whatever the language. A run started right after the sandbox was created waits for it to be ready. By default the call answers once the run has finished, with all of its output (up to its cap); `wait=false` answers at once with the queued run (follow it with GET …/runs/{run_id}/events), and `stream=true` answers with that event stream directly. A retry with the same `Idempotency-Key` never runs the code twice. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:update` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.runCode(…) Python: client.sandboxes.run_code(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - wait: true (default): answer when the run has finished. false: answer at once with the queued run; follow it with GET …/runs/{run_id}/events - stream: true: answer with the run’s events as a server-sent event stream (the same events as GET …/runs/{run_id}/events) Request body (JSON): - language (required): python (one interpreter per sandbox: state persists between runs), javascript (Node, a fresh process per run) or shell (bash, a fresh process per run) - code (required): Machine-readable code - stdin: Given to the code on standard input - timeout_seconds: Time limit (default 60) - max_output_bytes: stdout + stderr cap; the run is cut off past it (default 1048576) Response: 201 SandboxRun Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "language": "python", "code": "x = 21 * 2\nprint(x)", "timeout_seconds": 30 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.runCode('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', { language: 'python', code: 'x = 21 * 2 print(x)', timeout_seconds: 30, }); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.run_code( "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", language="python", code="x = 21 * 2\nprint(x)", timeout_seconds=30, ) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.runCode \ sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"language":"python","code":"x = 21 * 2\nprint(x)","timeout_seconds":30}' ``` ### One run: its outcome and recorded output URL: https://hayonix.ai/docs/reference/sandboxes/get-sandbox-run GET /v1/sandboxes/{sandbox_id}/runs/{run_id} One run: its outcome and recorded output Poll this after starting a run with `wait=false` until `state` is `completed` or `error`. The recorded output is the first 65536 bytes of each stream; for all of it, use the run’s response or its event stream. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.getRun(…) Python: client.sandboxes.get_run(…) Path parameters: - sandbox_id (required): ID of the sandbox - run_id (required): ID of the run Response: 200 SandboxRun Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs/sbr_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.getRun('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', 'sbr_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.get_run( "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", "sbr_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.getRun \ sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 \ sbr_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A run’s output as a server-sent event stream, from its start until it ends URL: https://hayonix.ai/docs/reference/sandboxes/stream-sandbox-run GET /v1/sandboxes/{sandbox_id}/runs/{run_id}/events A run’s output as a server-sent event stream, from its start until it ends Events: `run` (the run record, first and last), `started` (started_at), `output` (stream stdout|stderr, text) as it is produced, and finally `end`. Live output stays replayable for an hour after the run ends; after that the recorded output is sent instead. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.streamRun(…) Python: client.sandboxes.stream_run(…) Path parameters: - sandbox_id (required): ID of the sandbox - run_id (required): ID of the run Response: 200 a server-sent event stream (text/event-stream) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -N "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs/sbr_01jc5zq4m8k3v6x9t2w7r0b1e4/events" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const stream = await client.sandboxes.streamRun('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', 'sbr_01jc5zq4m8k3v6x9t2w7r0b1e4'); for await (const event of stream) { console.log(event.event, event.data); } ``` Python: ```python from hayonix import Client client = Client() for event in client.sandboxes.stream_run( "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", "sbr_01jc5zq4m8k3v6x9t2w7r0b1e4", ): print(event.event, event.data) ``` CLI: ```bash hayonix api sandboxes.streamRun \ sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 \ sbr_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Stop a queued or running run (a finished run is returned as it is) URL: https://hayonix.ai/docs/reference/sandboxes/cancel-sandbox-run POST /v1/sandboxes/{sandbox_id}/runs/{run_id}/cancel Stop a queued or running run (a finished run is returned as it is) The response can still show the run as `running`: it ends shortly after with `cut_off: cancelled` (a queued run never starts). Files in the workspace are kept. Calling it again is harmless. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:update` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.cancelRun(…) Python: client.sandboxes.cancel_run(…) Path parameters: - sandbox_id (required): ID of the sandbox - run_id (required): ID of the run Response: 200 SandboxRun Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs/sbr_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.cancelRun('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', 'sbr_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.cancel_run( "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", "sbr_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.cancelRun \ sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 \ sbr_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### List a directory of the sandbox’s workspace URL: https://hayonix.ai/docs/reference/sandboxes/list-sandbox-files GET /v1/sandboxes/{sandbox_id}/files List a directory of the sandbox’s workspace Lists one directory (not recursive), sorted by name, at most 1000 entries. Works only while the sandbox is running (409 `sandbox_not_ready` while it starts, `sandbox_ended` after it ends); like every file operation it counts as activity for the idle timeout. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.listFiles(…) Python: client.sandboxes.list_files(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - path: Relative to the workspace (/workspace); "" or "." is the workspace itself Response: 200 SandboxFileList Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/files" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.listFiles('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.list_files("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4") print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.listFiles sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Delete a file, or a directory with everything in it, from the workspace URL: https://hayonix.ai/docs/reference/sandboxes/delete-sandbox-file DELETE /v1/sandboxes/{sandbox_id}/files Delete a file, or a directory with everything in it, from the workspace Deletes what is at `path`; the workspace itself cannot be deleted. Works only while the sandbox is running. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:update` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.deleteFile(…) Python: client.sandboxes.delete_file(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - path: Relative to the workspace (/workspace); "" or "." is the workspace itself Response: 200 SandboxDeletedFile Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/files" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const sandboxe = await client.sandboxes.deleteFile('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(sandboxe); ``` Python: ```python from hayonix import Client client = Client() sandboxe = client.sandboxes.delete_file("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4") print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.deleteFile sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Download a file from the sandbox’s workspace (streamed) URL: https://hayonix.ai/docs/reference/sandboxes/download-sandbox-file GET /v1/sandboxes/{sandbox_id}/files/content Download a file from the sandbox’s workspace (streamed) Streams the file at `path` as an attachment; files larger than 67108864 bytes cannot be downloaded. Works only while the sandbox is running. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:read` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.downloadFile(…) Python: client.sandboxes.download_file(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - path: Relative to the workspace (/workspace); "" or "." is the workspace itself Response: 200 the file content (application/octet-stream) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/files/content" \ -H "Authorization: Bearer $API_KEY" \ -o output.bin ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const download = await client.sandboxes.downloadFile('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4'); await download.saveTo(download.filename ?? 'output.bin'); ``` Python: ```python from hayonix import Client client = Client() download = client.sandboxes.download_file("sbx_01jc5zq4m8k3v6x9t2w7r0b1e4") download.save(download.filename or "output.bin") ``` CLI: ```bash hayonix api sandboxes.downloadFile sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Upload a file into the sandbox’s workspace (replaces it; parents are created) URL: https://hayonix.ai/docs/reference/sandboxes/upload-sandbox-file PUT /v1/sandboxes/{sandbox_id}/files/content Upload a file into the sandbox’s workspace (replaces it; parents are created) Writes the body to `path`, replacing any file there; the file appears only once it is complete. At most 67108864 bytes (413 `file_too_large` beyond). Works only while the sandbox is running. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `sandbox:update` permission (a key's scope, or a role that includes it). TypeScript: client.sandboxes.uploadFile(…) Python: client.sandboxes.upload_file(…) Path parameters: - sandbox_id (required): ID of the sandbox Query parameters: - path: Relative to the workspace (/workspace); "" or "." is the workspace itself Request body (multipart form): - file (required): The file’s content Response: 200 SandboxUploadedFile Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PUT "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/files/content" \ -H "Authorization: Bearer $API_KEY" \ -F "file=@data.jsonl" ``` TypeScript: ```typescript import { Client } from 'hayonix'; import { fileFromPath } from 'hayonix/node'; const client = new Client(); const sandboxe = await client.sandboxes.uploadFile('sbx_01jc5zq4m8k3v6x9t2w7r0b1e4', { file: await fileFromPath('data.jsonl') }); console.log(sandboxe); ``` Python: ```python import pathlib from hayonix import Client client = Client() sandboxe = client.sandboxes.upload_file( "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4", file=pathlib.Path("data.jsonl"), ) print(sandboxe) ``` CLI: ```bash hayonix api sandboxes.uploadFile sbx_01jc5zq4m8k3v6x9t2w7r0b1e4 --param file=@data.jsonl ``` --- ## Clusters ### What a cluster of this shape costs per hour at today’s prices URL: https://hayonix.ai/docs/reference/clusters/estimate-cluster GET /v1/clusters/estimate What a cluster of this shape costs per hour at today’s prices Compute is billed per second from the start of each member’s run; the shared volume per GB-second while the cluster exists. Hourly figures are exact multiples of the per-second prices, except storage, which is rounded down for display. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:read` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.estimate(…) Python: client.clusters.estimate(…) Query parameters: - sku (required): Hardware SKU - gpu_count: GPUs per member - member_count: Number of members - shared_volume_gb: Shared volume size in GB (0: none) Response: 200 ClusterEstimate Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/clusters/estimate?sku=%3Csku%3E" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const cluster = await client.clusters.estimate({ sku: '' }); console.log(cluster); ``` Python: ```python from hayonix import Client client = Client() cluster = client.clusters.estimate(sku="") print(cluster) ``` CLI: ```bash hayonix api clusters.estimate --param sku='' ``` ### List clusters in the project, newest first (deleted ones only when asked for) URL: https://hayonix.ai/docs/reference/clusters/list-clusters GET /v1/clusters List clusters in the project, newest first (deleted ones only when asked for) Returns clusters with their state and members; pass `include_deleted=true` to list deleted ones as well. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:read` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.list(…) Python: client.clusters.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - include_deleted: Also list deleted clusters (default false) Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/clusters" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.clusters.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.clusters.list(): print(item) ``` CLI: ```bash hayonix api clusters.list ``` ### Create a cluster: every member is placed on a host at once, or nothing is created URL: https://hayonix.ai/docs/reference/clusters/create-cluster POST /v1/clusters Create a cluster: every member is placed on a host at once, or nothing is created Every member is placed before the request returns (launch gate, the `clusters`, `cluster_members` and `gpus` quotas apply). If any member does not fit, the request fails with 409 `insufficient_capacity` and nothing is created or billed. Members reach each other on a private network at fixed addresses, by the hostnames `member-` (and `head`); each is billed per second from the start of its run. A member that fails or loses its host makes the cluster `degraded`; nothing is restarted. A cluster’s configuration never changes after creation. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:create` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.create(…) Python: client.clusters.create(…) Request body (JSON): - name (required): Display name - member_count (required): Number of identical members (2–16); member 0 is the head - hardware (required): What each member runs on - region (required): Region every member is placed in - image: Container image (or give a template) - template_id: Template supplying the image and defaults - env: Environment variables of every member - secret_env: Environment variables taken from project secrets - command: Replaces the image entrypoint - args: Replaces the image command - container_disk_gb: Writable container disk of each member (default 50) - registry_credential_id: Credential for a private image - shared_volume: One volume mounted read-write at the same path on every member - one_member_per_host: Place every member on a host of its own (default false: members may share a host when it has room). When there are not enough such hosts the request fails with 409 `insufficient_capacity` and nothing is created. Response: 201 Cluster Errors: - 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: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 quota_exceeded_error: An organization quota is reached; `param` names it. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/clusters" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "name": "llm-train", "member_count": 2, "hardware": { "sku": "cpu-4c-16gb", "gpu_count": 0 }, "region": "dev-local-1", "image": "registry.example.com/team/train:1", "env": [ { "name": "GLOO_SOCKET_IFNAME", "value": "eth0" } ], "shared_volume": { "size_gb": 100, "mount_path": "/shared" } }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const cluster = await client.clusters.create({ name: 'llm-train', member_count: 2, hardware: { sku: 'cpu-4c-16gb', gpu_count: 0 }, region: 'dev-local-1', image: 'registry.example.com/team/train:1', env: [{ name: 'GLOO_SOCKET_IFNAME', value: 'eth0' }], shared_volume: { size_gb: 100, mount_path: '/shared' }, }); console.log(cluster); ``` Python: ```python from hayonix import Client client = Client() cluster = client.clusters.create( name="llm-train", member_count=2, hardware={"sku": "cpu-4c-16gb", "gpu_count": 0}, region="dev-local-1", image="registry.example.com/team/train:1", env=[{"name": "GLOO_SOCKET_IFNAME", "value": "eth0"}], shared_volume={"size_gb": 100, "mount_path": "/shared"}, ) print(cluster) ``` CLI: ```bash hayonix api clusters.create \ --body '{"name":"llm-train","member_count":2,"hardware":{"sku":"cpu-4c-16gb","gpu_count":0},"region":"dev-local-1","image":"registry.example.com/team/train:1","env":[{"name":"GLOO_SOCKET_IFNAME","value":"eth0"}],"shared_volume":{"size_gb":100,"mount_path":"/shared"}}' ``` ### Get a cluster: its state, its members (rank, host, address, state) and how to connect URL: https://hayonix.ai/docs/reference/clusters/get-cluster GET /v1/clusters/{cluster_id} Get a cluster: its state, its members (rank, host, address, state) and how to connect Each member carries the ready-to-run ssh command for the platform’s SSH gateway (the project’s SSH keys). From the head, run `$CLUSTER_RUNTIME_LAUNCHER ` to start a process on another member. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:read` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.get(…) Python: client.clusters.get(…) Path parameters: - cluster_id (required): ID of the cluster Response: 200 Cluster Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const cluster = await client.clusters.get('clu_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(cluster); ``` Python: ```python from hayonix import Client client = Client() cluster = client.clusters.get("clu_01jc5zq4m8k3v6x9t2w7r0b1e4") print(cluster) ``` CLI: ```bash hayonix api clusters.get clu_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Rename a cluster (nothing else about a cluster changes after creation) URL: https://hayonix.ai/docs/reference/clusters/update-cluster PATCH /v1/clusters/{cluster_id} Rename a cluster (nothing else about a cluster changes after creation) Only the display name can change; members, hardware and the network are fixed for the cluster’s life. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:update` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.update(…) Python: client.clusters.update(…) Path parameters: - cluster_id (required): ID of the cluster Request body (JSON): - name (required): New display name Response: 200 Cluster Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "llm-train-2" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const cluster = await client.clusters.update('clu_01jc5zq4m8k3v6x9t2w7r0b1e4', { name: 'llm-train-2' }); console.log(cluster); ``` Python: ```python from hayonix import Client client = Client() cluster = client.clusters.update("clu_01jc5zq4m8k3v6x9t2w7r0b1e4", name="llm-train-2") print(cluster) ``` CLI: ```bash hayonix api clusters.update \ clu_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"name":"llm-train-2"}' ``` ### Delete a cluster: every member, its network and its shared volume are destroyed URL: https://hayonix.ai/docs/reference/clusters/delete-cluster DELETE /v1/clusters/{cluster_id} Delete a cluster: every member, its network and its shared volume are destroyed Irreversible. Billing ends with each member’s container and the shared volume’s data is deleted on its host. Deleting a deleted cluster returns it unchanged. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:delete` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.delete(…) Python: client.clusters.delete(…) Path parameters: - cluster_id (required): ID of the cluster Response: 200 Cluster Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const cluster = await client.clusters.delete('clu_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(cluster); ``` Python: ```python from hayonix import Client client = Client() cluster = client.clusters.delete("clu_01jc5zq4m8k3v6x9t2w7r0b1e4") print(cluster) ``` CLI: ```bash hayonix api clusters.delete clu_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### The cluster’s timeline, oldest first URL: https://hayonix.ai/docs/reference/clusters/list-cluster-events GET /v1/clusters/{cluster_id}/events The cluster’s timeline, oldest first Created, running, degraded (which member, and why), stopped and deleted, with one sentence each. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:read` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.listEvents(…) Python: client.clusters.list_events(…) Path parameters: - cluster_id (required): ID of the cluster Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4/events" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.clusters.listEvents('clu_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.clusters.list_events("clu_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api clusters.listEvents clu_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### A member’s container output as a server-sent event stream URL: https://hayonix.ai/docs/reference/clusters/stream-cluster-member-logs GET /v1/clusters/{cluster_id}/members/{rank}/logs A member’s container output as a server-sent event stream Events: `output` (stream stdout|stderr, text, timestamp, instance_id), `notice` (why there is no output, e.g. the member is not on a host) and finally `end`. Output comes from the member’s host and is gone once its container is removed. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `cluster:read` permission (a key's scope, or a role that includes it). TypeScript: client.clusters.streamMemberLogs(…) Python: client.clusters.stream_member_logs(…) Path parameters: - cluster_id (required): ID of the cluster - rank: The member’s rank (0 is the head) Query parameters: - tail: Lines of past output to send first (default 200) - follow: Keep the stream open for new output (default false) Response: 200 a server-sent event stream (text/event-stream) Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -N "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4/members/0/logs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const stream = await client.clusters.streamMemberLogs('clu_01jc5zq4m8k3v6x9t2w7r0b1e4', '0'); for await (const event of stream) { console.log(event.event, event.data); } ``` Python: ```python from hayonix import Client client = Client() for event in client.clusters.stream_member_logs("clu_01jc5zq4m8k3v6x9t2w7r0b1e4", "0"): print(event.event, event.data) ``` CLI: ```bash hayonix api clusters.streamMemberLogs clu_01jc5zq4m8k3v6x9t2w7r0b1e4 0 ``` --- ## Usage ### Spend over time, grouped, with a breakdown table URL: https://hayonix.ai/docs/reference/usage/get-cost-report GET /v1/orgs/{org_id}/usage/costs Spend over time, grouped, with a breakdown table Every amount is exactly what was charged to the organization's balance, dated by when the usage happened, so totals match the billing history to the nano-USD. Daily buckets cover at most 400 days and hourly buckets at most 31; an API key sees only its own project's spend. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `usage:read` permission (a key's scope, or a role that includes it). TypeScript: client.usage.getCostReport(…) Python: client.usage.get_cost_report(…) Path parameters: - org_id (required): ID of the organization Query parameters: - start: Inclusive; default the start of the current month (UTC) - end: Exclusive; default the start of next month - bucket: Default day (UTC) - group_by: Default product - project_id: ID of the project Response: 200 CostReport Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/usage/costs" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.usage.getCostReport(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.usage.get_cost_report() print(result) ``` CLI: ```bash hayonix api usage.getCostReport ``` ### The cost report as CSV URL: https://hayonix.ai/docs/reference/usage/export-cost-report GET /v1/orgs/{org_id}/usage/costs/export The cost report as CSV The same report as `getCostReport`, downloaded as a CSV file: one row per bucket and group with the amount in nano-USD and in USD, then a final `total` row. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `usage:read` permission (a key's scope, or a role that includes it). TypeScript: client.usage.exportCostReport(…) Python: client.usage.export_cost_report(…) Path parameters: - org_id (required): ID of the organization Query parameters: - start: Inclusive; default the start of the current month (UTC) - end: Exclusive; default the start of next month - bucket: Default day (UTC) - group_by: Default product - project_id: ID of the project Response: 200 text (text/csv) Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/usage/costs/export" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.usage.exportCostReport(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.usage.export_cost_report() print(result) ``` CLI: ```bash hayonix api usage.exportCostReport ``` ### The current month's spend by product URL: https://hayonix.ai/docs/reference/usage/get-usage-summary GET /v1/orgs/{org_id}/usage/summary The current month's spend by product Spend from the start of the current UTC month up to now, per product, computed the same way as the cost report. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `usage:read` permission (a key's scope, or a role that includes it). TypeScript: client.usage.getSummary(…) Python: client.usage.get_summary(…) Path parameters: - org_id (required): ID of the organization Response: 200 UsageSummary Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash # The org of your key: GET /v1/caller ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id) curl -sS "$API_BASE_URL/orgs/$ORG_ID/usage/summary" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const result = await client.usage.getSummary(); console.log(result); ``` Python: ```python from hayonix import Client client = Client() result = client.usage.get_summary() print(result) ``` CLI: ```bash hayonix api usage.getSummary ``` --- ## Webhooks ### Every event type a webhook can receive, with the JSON Schema of its data URL: https://hayonix.ai/docs/reference/webhooks/list-webhook-event-types GET /v1/webhooks/event-types Every event type a webhook can receive, with the JSON Schema of its data The whole catalogue in one response (`next_cursor` is always null). Needs no authentication. Authentication: None: this operation is public. TypeScript: client.webhooks.listEventTypes(…) Python: client.webhooks.list_event_types(…) Response: 200 JSON Errors: - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks/event-types" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.listEventTypes(); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.list_event_types() print(webhook) ``` CLI: ```bash hayonix api webhooks.listEventTypes ``` ### List the project’s webhook destinations, with their delivery health URL: https://hayonix.ai/docs/reference/webhooks/list-webhooks GET /v1/webhooks List the project’s webhook destinations, with their delivery health Newest first. Signing secrets are never included. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:read` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.list(…) Python: client.webhooks.list(…) Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page Response: 200 a page of results Errors: - 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. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.webhooks.list()) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.webhooks.list(): print(item) ``` CLI: ```bash hayonix api webhooks.list ``` ### Create a webhook destination (its signing secret is returned once) URL: https://hayonix.ai/docs/reference/webhooks/create-webhook POST /v1/webhooks Create a webhook destination (its signing secret is returned once) Events of the chosen types that happen in this project are POSTed to the URL from now on, signed with the secret in this response, which cannot be read again. Delivery is at least once and in no promised order: deduplicate on the `Webhook-Id` header. A project can have up to 20 destinations. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:create` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.create(…) Python: client.webhooks.create(…) Request body (JSON): - url (required): Where events are POSTed: an https URL (plain http is accepted only by development deployments). Addresses that resolve to loopback, private, link-local or metadata networks are refused when delivering. - description: Free-text description - event_types: Event types to receive, or `["*"]` for every type (GET /v1/webhooks/event-types lists them). Organization events (billing) need `org_events: true`. - org_events: Also receive organization events (billing: low balance, out of credit, payments, auto-recharge). Needs billing:read. Response: 201 CreatedWebhook Errors: - 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. - 409 conflict_error: A request with the same Idempotency-Key is still running. - 422 idempotency_error: The Idempotency-Key was used with a different request. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.example.com/platform", "description": "Ops alerts", "event_types": [ "pod.stopped", "pod.host_lost" ], "org_events": false }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.create({ url: 'https://hooks.example.com/platform', description: 'Ops alerts', event_types: ['pod.stopped', 'pod.host_lost'], org_events: false, }); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.create( url="https://hooks.example.com/platform", description="Ops alerts", event_types=["pod.stopped", "pod.host_lost"], org_events=False, ) print(webhook) ``` CLI: ```bash hayonix api webhooks.create \ --body '{"url":"https://hooks.example.com/platform","description":"Ops alerts","event_types":["pod.stopped","pod.host_lost"],"org_events":false}' ``` ### Get a webhook destination URL: https://hayonix.ai/docs/reference/webhooks/get-webhook GET /v1/webhooks/{webhook_id} Get a webhook destination Returns the destination with its delivery health; the signing secret is never included. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:read` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.get(…) Python: client.webhooks.get(…) Path parameters: - webhook_id (required): ID of the webhook Response: 200 Webhook Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.get('whk_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.get("whk_01jc5zq4m8k3v6x9t2w7r0b1e4") print(webhook) ``` CLI: ```bash hayonix api webhooks.get whk_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Change a webhook destination, or pause or resume it URL: https://hayonix.ai/docs/reference/webhooks/update-webhook PATCH /v1/webhooks/{webhook_id} Change a webhook destination, or pause or resume it Fields you omit are left as they are. Pausing gives up its pending deliveries (redeliver them after resuming); resuming clears the failure streak. Changes apply to events from then on. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:update` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.update(…) Python: client.webhooks.update(…) Path parameters: - webhook_id (required): ID of the webhook Request body (JSON): - url: Where events are POSTed: an https URL (plain http is accepted only by development deployments). Addresses that resolve to loopback, private, link-local or metadata networks are refused when delivering. - description: Free-text description - event_types: Event types to receive, or `["*"]` for every type (GET /v1/webhooks/event-types lists them). Organization events (billing) need `org_events: true`. - org_events: Also receive organization events (billing). Turning it on needs billing:read. - status: `paused` stops sending (pending deliveries are given up; redeliver them after resuming); `active` resumes and clears the failure streak. Response: 200 Webhook Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X PATCH "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "active" }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.update('whk_01jc5zq4m8k3v6x9t2w7r0b1e4', { status: 'active' }); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.update("whk_01jc5zq4m8k3v6x9t2w7r0b1e4", status="active") print(webhook) ``` CLI: ```bash hayonix api webhooks.update whk_01jc5zq4m8k3v6x9t2w7r0b1e4 --body '{"status":"active"}' ``` ### Delete a webhook destination and its delivery log URL: https://hayonix.ai/docs/reference/webhooks/delete-webhook DELETE /v1/webhooks/{webhook_id} Delete a webhook destination and its delivery log Nothing more is sent to it, including deliveries still waiting to be retried. This cannot be undone. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:delete` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.delete(…) Python: client.webhooks.delete(…) Path parameters: - webhook_id (required): ID of the webhook Response: 200 JSON Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X DELETE "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.delete('whk_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.delete("whk_01jc5zq4m8k3v6x9t2w7r0b1e4") print(webhook) ``` CLI: ```bash hayonix api webhooks.delete whk_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Replace the signing secret (returned once); the previous one keeps signing during the overlap URL: https://hayonix.ai/docs/reference/webhooks/rotate-webhook-secret POST /v1/webhooks/{webhook_id}/rotate-secret Replace the signing secret (returned once); the previous one keeps signing during the overlap During the overlap every delivery carries two signatures in `Webhook-Signature`, one per secret, so you can switch your receiver to the new secret without missing events. The body is optional. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:update` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.rotateSecret(…) Python: client.webhooks.rotate_secret(…) Path parameters: - webhook_id (required): ID of the webhook Request body (JSON): - overlap_seconds: How long the previous secret keeps signing deliveries next to the new one (default 86400; 0 revokes it at once) Response: 200 WebhookSecret Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4/rotate-secret" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "overlap_seconds": 86400 }' ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.rotateSecret('whk_01jc5zq4m8k3v6x9t2w7r0b1e4', { overlap_seconds: 86400 }); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.rotate_secret( "whk_01jc5zq4m8k3v6x9t2w7r0b1e4", overlap_seconds=86400, ) print(webhook) ``` CLI: ```bash hayonix api webhooks.rotateSecret \ whk_01jc5zq4m8k3v6x9t2w7r0b1e4 \ --body '{"overlap_seconds":86400}' ``` ### Send a test event to this destination (also while it is paused) URL: https://hayonix.ai/docs/reference/webhooks/send-webhook-test POST /v1/webhooks/{webhook_id}/test Send a test event to this destination (also while it is paused) Queues a signed `webhook.test` event and returns its delivery; follow it through the delivery routes to check that your endpoint receives and verifies events. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:update` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.sendTest(…) Python: client.webhooks.send_test(…) Path parameters: - webhook_id (required): ID of the webhook Response: 200 WebhookEventDelivery Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4/test" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.sendTest('whk_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.send_test("whk_01jc5zq4m8k3v6x9t2w7r0b1e4") print(webhook) ``` CLI: ```bash hayonix api webhooks.sendTest whk_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### List a destination’s deliveries, newest first URL: https://hayonix.ai/docs/reference/webhooks/list-webhook-deliveries GET /v1/webhooks/{webhook_id}/deliveries List a destination’s deliveries, newest first One delivery per event sent to this destination (plus redeliveries), with its latest result. Deliveries are kept for 30 days. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:read` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.listDeliveries(…) Python: client.webhooks.list_deliveries(…) Path parameters: - webhook_id (required): ID of the webhook Query parameters: - limit: 1–200, default 50 - cursor: `next_cursor` of the previous page - status: Only deliveries in this state - event_type: Only deliveries of this event type Response: 200 a page of results Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4/deliveries" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); for await (const item of client.webhooks.listDeliveries('whk_01jc5zq4m8k3v6x9t2w7r0b1e4')) { console.log(item); } ``` Python: ```python from hayonix import Client client = Client() for item in client.webhooks.list_deliveries("whk_01jc5zq4m8k3v6x9t2w7r0b1e4"): print(item) ``` CLI: ```bash hayonix api webhooks.listDeliveries whk_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Get a delivery with its payload and attempt log URL: https://hayonix.ai/docs/reference/webhooks/get-webhook-delivery GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id} Get a delivery with its payload and attempt log Returns the body that is sent and every attempt so far, with the status code, error, duration and the start of your endpoint’s response. Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:read` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.getDelivery(…) Python: client.webhooks.get_delivery(…) Path parameters: - webhook_id (required): ID of the webhook - delivery_id (required): ID of the delivery Response: 200 WebhookEventDeliveryDetail Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4/deliveries/whd_01jc5zq4m8k3v6x9t2w7r0b1e4" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.getDelivery('whk_01jc5zq4m8k3v6x9t2w7r0b1e4', 'whd_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.get_delivery( "whk_01jc5zq4m8k3v6x9t2w7r0b1e4", "whd_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(webhook) ``` CLI: ```bash hayonix api webhooks.getDelivery \ whk_01jc5zq4m8k3v6x9t2w7r0b1e4 \ whd_01jc5zq4m8k3v6x9t2w7r0b1e4 ``` ### Send a delivery’s event again (a new delivery, same event ID) URL: https://hayonix.ai/docs/reference/webhooks/redeliver-webhook POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver Send a delivery’s event again (a new delivery, same event ID) Creates a new delivery of the same payload with the same `Webhook-Id`, so a receiver that already handled the event can skip it. The destination must be active (409 `webhook_paused` otherwise). Authentication: Project API key (Authorization: Bearer sk_…), or a console session. Requires the `webhook:update` permission (a key's scope, or a role that includes it). TypeScript: client.webhooks.redeliver(…) Python: client.webhooks.redeliver(…) Path parameters: - webhook_id (required): ID of the webhook - delivery_id (required): ID of the delivery Response: 200 WebhookEventDelivery Errors: - 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. - 404 not_found_error: No such resource in this project (an ID from another project is answered the same way). - 409 conflict_error: The resource's current state does not allow this. - 429 rate_limit_error: Too many requests; retry after `retry-after` seconds. Examples: curl: ```bash curl -sS -X POST "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4/deliveries/whd_01jc5zq4m8k3v6x9t2w7r0b1e4/redeliver" \ -H "Authorization: Bearer $API_KEY" ``` TypeScript: ```typescript import { Client } from 'hayonix'; const client = new Client(); const webhook = await client.webhooks.redeliver('whk_01jc5zq4m8k3v6x9t2w7r0b1e4', 'whd_01jc5zq4m8k3v6x9t2w7r0b1e4'); console.log(webhook); ``` Python: ```python from hayonix import Client client = Client() webhook = client.webhooks.redeliver( "whk_01jc5zq4m8k3v6x9t2w7r0b1e4", "whd_01jc5zq4m8k3v6x9t2w7r0b1e4", ) print(webhook) ``` CLI: ```bash hayonix api webhooks.redeliver \ whk_01jc5zq4m8k3v6x9t2w7r0b1e4 \ whd_01jc5zq4m8k3v6x9t2w7r0b1e4 ```