Skip to content

API reference ​

Every endpoint under https://cloud.theyilabs.com/v1, how to call it, and what comes back.

Basics ​

  • Base URL: https://cloud.theyilabs.com/v1. The Anthropic SDKs take https://cloud.theyilabs.com and add /v1 themselves.
  • Authentication: Authorization: Bearer <key>. On /v1/messages, x-api-key: <key> works too. Keys look like pwc_live_…. See API keys and limits.
  • Bodies: JSON with Content-Type: application/json, except file uploads, which are application/octet-stream.
  • Request IDs: every request gets an ID that starts with req_. Successful model answers carry it in the x-request-id header, and every error body includes it as request_id.

Idempotency-Key ​

Creating, deleting and every VM action (start, stop, reboot, reinstall, renew) need an Idempotency-Key header: 8 to 120 characters of letters, digits, ., _, : and -. A UUID works.

  • If a request fails on the network, send it again with the same key and the same body. You get the result of the first request instead of a second resource or a second charge.
  • The same key with different parameters gets 409 conflict.
  • Keys belong to your workspace. Use a new key for each new operation.

Commands (exec) are never repeated for you and take no key. If an exec call fails on the network, check the sandbox before running the command again.

Money ​

Amounts are whole numbers of micro-dollars: 1 USD = 1,000,000 micro-dollars. Balances and charges commonly use the _micro suffix; rate fields also specify a time or token unit.

In GET /v1/catalog, price.input, price.output and price.cachedInput are base prices in micro-dollars per million tokens, without the _micro suffix. price.markup is a unitless multiplier; price.effectiveAt is when the price takes effect. A null cachedInput uses the input base price. price.imageOutput is the image output price of an image model, and null for other models.

For total input tokens I, cached input tokens C within that total, output tokens O (text and thinking) and image output tokens G, calculate the charge in micro-dollars and round up:

text
ceil(((I - C) * input + C * (cachedInput ?? input) + O * output + G * (imageOutput ?? output)) * markup / 1,000,000)

Read current prices from the catalog. Usage records and receipts show the amount charged.

Limits ​

LimitValue
Body of a model request4 MiB
Body of any other request1 MiB
File piece, upload or download64 KiB
Command output without streaming1 MiB
Commands running at once in one sandbox4
Items in a list200 most recent
Requests per minuteAs set on the key

Model request limits are in Models API. Compute quotas are in Quotas and network.

Errors ​

Every error has the same shape:

json
{
  "error": {
    "code": "insufficient_funds",
    "message": "Not enough available balance",
    "request_id": "req_…"
  }
}
StatuscodeMeaning
400invalid_requestA field is missing or not accepted. The message says which.
400upstream_invalid_request, content_filterThe model rejected the input, or refused the content.
401invalid_keyNo key, a malformed key, an unknown key, or a revoked or expired one.
402insufficient_fundsThe available balance can't cover the hold.
402key_limit_reachedThe key's spend limit can't cover the hold.
403forbiddenThe key may not be used here, your workspace is suspended, or the resource is closed off for review.
404not_foundNo such model, resource, file or path in your workspace.
409conflictThe resource isn't in a state for this, or an Idempotency-Key was reused with other parameters.
409quota_exceededYour quota for resources, vCPUs or lifetime.
413payload_too_largeThe body is over the limit.
429rate_limitedThe key's requests-per-minute limit. Wait the seconds in Retry-After.
500internalSomething failed on our side. Try again later.
502upstream_failed, provider_authentication, provider_configuration, response_too_largeNo model deployment gave a usable answer.
502no_imageThe image model ended without an image.
503upstream_unavailableA service is paused or not answering (the Yi Labs account included), the architecture isn't available, or a command or file call couldn't be carried out. Try again shortly.
503upstream_capacityThe model is busy.
504upstream_timeoutNo model deployment answered in time.

What to do about each is in Troubleshooting.

Public endpoints ​

No key needed.

EndpointReturns
GET /v1/catalog{"models": [...]}: each enabled model with id, name, kind, price, responses_api and max_output_tokens.
GET /v1/compute/classesclasses: each size with id, vcpu, memory_gb, disk_gb, price_micro_per_hour and stopped_micro_per_hour. pools: the resource pools pool accepts (pool-1, pool-2, pool-3), each with its architectures.

Moving from cloud to pool ​

The size endpoint remains GET /v1/compute/classes, with the same classes array. Its clouds field becomes pools; create requests and resource answers use pool. Omit the optional pool to let the service choose, or select an id from the current pools list. The old cloud field returns 400 invalid_request; it is neither ignored nor converted.

Models ​

Key with "Model API".

Endpoint
GET /v1/modelsOpenAI-style list of the models this key may use.
POST /v1/chat/completionsOpenAI chat completions.
POST /v1/responsesOpenAI Responses, for models with responses_api: true.
POST /v1/embeddingsOpenAI embeddings.
POST /v1/messagesAnthropic Messages.
POST /v1/images/generationsOpenAI image generation, for image models. See Image generation.

What each accepts is in Models API.

Sandboxes ​

Key with "Sandboxes".

EndpointIdempotency-Key
POST /v1/sandboxesYesCreate. Body: class, and optionally arch, pool, timeout_s, idle_timeout_s, metadata. Answers 202 with the resource.
GET /v1/sandboxes{"resources": [...]}, the 200 most recent.
GET /v1/sandboxes/{id}The resource.
DELETE /v1/sandboxes/{id}YesDelete. Answers 202 with the resource.
POST /v1/sandboxes/{id}/keepaliveResets the idle time. Answers {"ok": true}.
POST /v1/sandboxes/{id}/execRun a command. Body: cmd, and optionally cwd, env, timeout_s, stream.
GET /v1/sandboxes/{id}/files?path=…Read up to 64 KiB, chosen with a Range: bytes=start-end header. Answers 200 or 206 with Content-Range.
PUT /v1/sandboxes/{id}/files?path=…&offset=…&truncate=…Write up to 64 KiB of application/octet-stream at offset. Answers 204.
GET /v1/sandboxes/{id}/receiptThe receipt. ?format=csv for CSV.

exec, files and keepalive need the sandbox to be ready or busy. Otherwise they get 409 conflict. Details in Sandboxes.

VMs ​

Key with "VMs".

EndpointIdempotency-Key
POST /v1/vmsYesCreate. Body: class, ssh_public_keys, allowed_cidrs, and optionally arch, pool, hours, metadata. Answers 202 with the resource.
GET /v1/vms{"resources": [...]}, the 200 most recent.
GET /v1/vms/{id}The resource.
DELETE /v1/vms/{id}YesDelete, disk included. Answers 202.
POST /v1/vms/{id}/startYesStart a stopped VM. Needs prepaid time left.
POST /v1/vms/{id}/stopYesStop.
POST /v1/vms/{id}/rebootYesRestart a running VM.
POST /v1/vms/{id}/reinstallYesErase the system disk and reinstall. Body: {"confirm_destroy_disk": true}.
POST /v1/vms/{id}/renewYesExtend the lease. Body: {"hours": n}, 1 to 168. Charged at once.
GET /v1/vms/{id}/serialThe last 64 KiB of boot serial output, as text.
GET /v1/vms/{id}/receiptThe receipt. ?format=csv for CSV.

Actions answer 202 with the resource. Details in VMs.

The resource object ​

Sandboxes and VMs come back in the same shape.

Field
idsb_… or vm_….
kindsandbox or vm.
class, arch, poolWhat it was created with.
cpu, memory_gb, disk_gbIts size.
stateWhere it is now. See Sandboxes and VMs.
desiredWhere it's heading: running, stopped or deleted.
price_micro_per_hour, stopped_micro_per_hourIts prices, fixed when it was created.
public_ipA VM's address once it runs. Sandboxes have none.
ssh_user, allowed_cidrsHow to reach a VM over SSH.
timeout_s, idle_timeout_sA sandbox's lifetime and idle time. For a VM, timeout_s is the first lease in seconds.
prepaid_until, stopped_atA VM's lease end, and when it stopped.
trust_tierYour trust tier when the resource was created.
metadataWhat you sent.
created_at, ready_atWhen it was requested and when it first became ready or ran.
error_codeWhy it ended or stopped, if it wasn't you. See Troubleshooting.
isolatedtrue if we closed it off for review. Only stop and delete work then.

The receipt ​

GET /v1/{sandboxes|vms}/{id}/receipt answers:

Field
resource_id, stateThe resource and its state.
currencyUSD.
price_micro_per_hour, stopped_micro_per_hourIts prices.
rowsEach charge: kind (sandbox_seconds, vm_hours or vm_disk_gb_hours), quantity, amount_micro and occurred_at.
total_microThe sum of rows.
balance_micro, available_microYour workspace's balance and available balance now.
as_ofWhen the receipt was made.
finaltrue once the resource has ended and nothing more will be charged.

With ?format=csv you get resource,kind,quantity,amount_micro,occurred_at.