Management API · HostYourAI

Use the Management API to script the full lifecycle of your resources: create a dedicated GPU instance, use it, delete it when you are done, and manage your API keys (create, rotate, revoke). Everything runs on the same host (https://hostyourai.com) and authenticates with the same hyai-rt-* key you use for inference. There is no separate token type.

1. Authentication

Send your API key as a Bearer token with every request:

Authorization: Bearer hyai-rt-...

Create a key in the app under API keys, or deploy your first instance: an account without a key gets one automatically. A key manages only the resources of its own account; team keys and embedded tenant keys cannot manage anything.

2. Instances

An instance either exists or it does not. There is no pause state: while it runs you pay the hourly price per minute, and deleting it stops billing immediately. Recreating one later is just another create call.

List

GET /api/v1/instances

Create (deploy)

curl -X POST https://hostyourai.com/api/v1/instances \
  -H "Authorization: Bearer hyai-rt-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id":      "llama-3.2-1b",
    "region":        "EU",
    "instance_type": "text"
  }'

Same fields, validation and credit check as the deploy wizard. Optional: custom_model_path (any HuggingFace repo), custom_min_vram, gpu_name, gpu_count, hf_token (your own HF token for gated repos, encrypted at rest). Returns the instance with status: "deploying"; a background job allocates the GPU and pulls the model.

Status

GET /api/v1/instances/{id}

Status values: pending, deploying, running, failed. Poll at most once per few seconds. While your own instance is still deploying, inference calls for its model return 503 with a Retry-After header and an honest ETA.

Delete

DELETE /api/v1/instances/{id}

Destroys the GPU at the provider; billing stops immediately. If the provider does not confirm the teardown, the instance stays visible so nothing keeps billing invisibly.

Private connection (WireGuard VPN)

Add "vpn": true to the create call and the instance becomes a WireGuard endpoint on our own EU hardware. You talk to the model through the tunnel, directly on the GPU, without our platform in between. The model port is closed to the public internet; only the tunnel and our platform (health checks, Playground) can reach it. Optional: vpn_client_public_key (your own WireGuard public key, base64). Without it we generate the client key pair for you.

curl -X POST https://hostyourai.com/api/v1/instances \
  -H "Authorization: Bearer hyai-rt-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "llama-3.2-1b",
    "region":   "EU",
    "vpn":      true
  }'

GET /api/v1/instances/{id}/vpn

The VPN call returns endpoint (public IP and UDP port of the instance), server_public_key, client_address, base_urls (TLS on port 8000 with the self-signed tls_cert, plain HTTP on port 8080 inside the tunnel only), api_key for calls inside the tunnel, and client_config: a ready-to-use wg0.conf. Keys stay the same for the life of the instance; after an automatic restart on new hardware only the endpoint changes, so re-read this call when the tunnel drops. Available on our own hardware only (UpCloud, Scaleway); the provider is chosen for you when you ask for a VPN.

3. API keys

List

GET /api/v1/keys

Create

POST /api/v1/keys
{ "name": "production" }

The plaintext key is returned once, in the key field of the response.

Rotate

POST /api/v1/keys/{id}/rotate

Same key row, new secret. The old secret stops working immediately; the response contains the new one. You may rotate the key you are calling with.

Revoke

DELETE /api/v1/keys/{id}

4. Inference

The same key does inference on the OpenAI-compatible endpoint. Your own dedicated instances show up in GET /api/v1/models marked "owned": true, under the model name you deployed; tokens on your own hardware cost nothing on top of the hourly price.

curl https://hostyourai.com/api/v1/chat/completions \
  -H "Authorization: Bearer hyai-rt-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"llama-3.2-1b","messages":[{"role":"user","content":"Hi"}]}'

5. End-to-end example: batch job

# 1. Create an instance
curl -X POST https://hostyourai.com/api/v1/instances \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model_id":"llama-3.2-1b","region":"EU","instance_type":"text"}'
# → { "id": 42, "status": "deploying", ... }

# 2. Poll until running
curl https://hostyourai.com/api/v1/instances/42 -H "Authorization: Bearer $KEY"
# → { "status": "running", ... }

# 3. Run your job with the same key
curl https://hostyourai.com/api/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"llama-3.2-1b","messages":[{"role":"user","content":"..."}]}'

# 4. Done? Delete, billing stops now
curl -X DELETE https://hostyourai.com/api/v1/instances/42 \
  -H "Authorization: Bearer $KEY"

6. Billing

Dedicated instances bill per minute at the hourly price shown at deploy time, from the moment the model is ready and answering; searching, booting and installing are free. Shared router models bill per token. Optional automatic top-up (Settings → Billing) refills your balance from a saved card when it drops below your threshold, so long-running jobs never stall on credit.

7. Conventions

Errors follow the OpenAI error shape: { "error": { "message", "type", "code" } }.
All timestamps are ISO 8601, UTC. Currency: EUR.
Model discovery: GET /api/v1/models (with your key) or GET /api/router/catalog in the app.

Questions?

info@hostyourai.com