{"openapi":"3.1.0","info":{"title":"Runtime Cloud API","version":"0.2.0","description":"One API for every Runtime Cloud product. Bearer key auth (or a sandbox session's token, `rtsess_...`, which reaches only the commands, files and previews of its one sandbox and is the only bearer the API answers CORS for), JSON everywhere, integer microdollars for money, `{data, nextCursor}` pages, Idempotency-Key on writes, `Prefer: wait=N` for long-running results, and an x-request-id on every response."},"servers":[{"url":"https://api.withruntime.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key (rtcloud_...), or a sandbox session (rtsess_...) from POST /v1/sandboxes/{id}/sessions for a browser: one sandbox's commands, files and previews, for an hour unless asked and a day at most."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/me":{"get":{"operationId":"account.me","summary":"Who this key is: its organization, agent and credential.","tags":["account"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","description":"The organization this key acts for."},"principalId":{"type":"string","description":"The agent this key belongs to."},"credentialId":{"type":["string","null"]},"apiVersion":{"type":"string"},"orgName":{"type":["string","null"],"description":"The account's name, as its members see it."},"role":{"type":["string","null"],"description":"The role of the member who made this key: owner, admin, developer or billing. It bounds what the key may do."},"compartment":{"type":["object","null"],"description":"The compartment this key is limited to, or null for a key that is in none. A key in a compartment reaches only what its compartment's keys made.","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["orgId","principalId","credentialId","apiVersion"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/usage":{"get":{"operationId":"account.usage","summary":"Usage and credit: balance, holds, free usage, startup hours, a pilot's sandbox-hours and per-resource charges, in integer microdollars.","tags":["account"],"parameters":[{"name":"key","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"A key's id (POST /v1/keys and GET /v1/keys give it): adds that key's own spend as `key`. A key reads itself, the keys it made, and any key its reads reach."},"description":"A key's id (POST /v1/keys and GET /v1/keys give it): adds that key's own spend as `key`. A key reads itself, the keys it made, and any key its reads reach."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string"},"unit":{"type":"string","const":"microdollars"},"credited":{"type":"string","pattern":"^-?[0-9]+$","description":"Every credit ever added: purchases and grants. Integer microdollars, as a string."},"spent":{"type":"string","pattern":"^-?[0-9]+$","description":"Settled usage, including what refunds and disputes took back. Integer microdollars, as a string."},"held":{"type":"string","pattern":"^-?[0-9]+$","description":"Reserved against running and paused work, not yet settled. Integer microdollars, as a string."},"expired":{"type":"string","pattern":"^-?[0-9]+$","description":"Credit that expired, or grant credit taken back. Integer microdollars, as a string."},"available":{"type":"string","pattern":"^-?[0-9]+$","description":"What can still be spent: credited - spent - expired - held. Integer microdollars, as a string."},"takenBack":{"type":"string","pattern":"^-?[0-9]+$","description":"The part of spent that refunds and disputes took. Integer microdollars, as a string."},"trial":{"type":["object","null"],"description":"Machine time an account without credit can still run, in milliseconds, or null when the account has none. GET /v1/limits describes each field.","properties":{"totalMs":{"type":"integer","minimum":0},"usedMs":{"type":"integer","minimum":0},"reservedMs":{"type":"integer","minimum":0},"availableMs":{"type":"integer","minimum":0},"offer":{"type":"string","enum":["hours","monthly"]},"renewsAt":{"type":"string","format":"date-time"}}},"outbound":{"type":["object","null"],"description":"Outbound traffic this calendar month (UTC): bytes the account's sandboxes sent to the internet, the part the monthly free usage covered, the part charged at the quoted rate, and what that cost.","properties":{"month":{"type":"string","description":"The month, YYYY-MM."},"sentBytes":{"type":"integer","minimum":0},"freeBytes":{"type":"integer","minimum":0},"billableBytes":{"type":"integer","minimum":0},"allowanceBytes":{"type":"integer","minimum":0},"chargedMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"Charged for outbound traffic this month. Integer microdollars, as a string."},"writtenOffMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"Owed for outbound traffic this month but not charged, because credit or a spending limit ran out. Integer microdollars, as a string."}}},"allowances":{"type":"array","items":{"type":"object","properties":{"pool":{"type":"string","description":"machine-memory, machine-cpu, saved-copies (snapshots, images, backups) or disks (volumes)."},"unit":{"type":"string","description":"GiB-hour, vCPU-hour or GB-month."},"quantity":{"type":"number","description":"What the month allows, in unit."},"used":{"type":"number","description":"Used by what has settled this month."},"reserved":{"type":"number","description":"Held for what is running now; given back unless used."},"left":{"type":"number","description":"Left this month: quantity less used. What is reserved is not taken off."},"month":{"type":"string","description":"The month's first day, YYYY-MM-DD (UTC)."},"renewsAt":{"type":"string","description":"When the next month's free usage starts, ISO 8601 UTC."},"freeUntil":{"type":["string","null"],"description":"When the free machine time ends for an account that has never paid: 30 days after it opened, ISO 8601 UTC. Null once the account has paid, when it renews every month."}}},"description":"What the account uses free, drawn before credit and never charged. With no credit, a product whose free usage is used is refused (included_usage_used_up) and its running sandboxes pause, until the 1st (an account that has paid) or until credit is added."},"startupIncluded":{"type":"array","items":{"type":"object","properties":{"pool":{"type":"string","description":"machine-cpu, machine-memory, saved-copies (snapshots, images and backups) or disks (volumes)."},"unit":{"type":"string","description":"vCPU-hour or GiB-hour for startup hours given once; GB for storage kept free each month."},"period":{"type":"string","description":"once: a quantity given once and used up by what runs (machine-cpu, machine-memory). month: quantity GB added to each month's included storage until expiresAt, never used up; storage past it bills at the published rate (saved-copies, disks)."},"quantity":{"type":"number","description":"What Runtime for Startups includes, in unit: once for machine time, or each month for storage."},"used":{"type":["number","null"],"description":"Used by what has settled; null for monthly storage."},"reserved":{"type":["number","null"],"description":"Held for what is running now; given back unless used. Null for monthly storage."},"left":{"type":["number","null"],"description":"Left: quantity less used. What is reserved is not taken off. Null for monthly storage."},"keptGB":{"type":["number","null"],"description":"Storage kept now (decimal GB); null for startup hours given once."},"source":{"type":"string","description":"startup: the account was accepted to Runtime for Startups."},"grantedAt":{"type":"string","description":"When it was given, ISO 8601 UTC."},"expiresAt":{"type":"string","description":"12 months after grantedAt, ISO 8601 UTC: what is left then is gone."}}},"description":"What Runtime for Startups includes: empty unless the account was accepted to it or given it. Machine time (startup hours) is given once, used after this month's free usage and before credit, never renewed, and gone after 12 months; storage is GB kept free each month for those 12 months."},"startupLimits":{"type":["object","null"],"description":"What Runtime for Startups includes at once for its 12 months, or null without it or after them, when the account's own limits apply: image builds, and sandboxes (past it, a create answers quota_exceeded).","properties":{"buildsAtOnce":{"type":"integer","minimum":1},"sandboxesAtOnce":{"type":"integer","minimum":1}},"required":["buildsAtOnce","sandboxesAtOnce"],"additionalProperties":false},"pot":{"type":"array","items":{"type":"object","properties":{"pool":{"type":"string","description":"machine-cpu, machine-memory, saved-copies (snapshots, images and backups) or disks (volumes)."},"unit":{"type":"string","description":"vCPU-hour or GiB-hour for startup hours given once; GB for storage kept free each month."},"period":{"type":"string","description":"once: a quantity given once and used up by what runs (machine-cpu, machine-memory). month: quantity GB added to each month's included storage until expiresAt, never used up; storage past it bills at the published rate (saved-copies, disks)."},"quantity":{"type":"number","description":"What Runtime for Startups includes, in unit: once for machine time, or each month for storage."},"used":{"type":["number","null"],"description":"Used by what has settled; null for monthly storage."},"reserved":{"type":["number","null"],"description":"Held for what is running now; given back unless used. Null for monthly storage."},"left":{"type":["number","null"],"description":"Left: quantity less used. What is reserved is not taken off. Null for monthly storage."},"keptGB":{"type":["number","null"],"description":"Storage kept now (decimal GB); null for startup hours given once."},"source":{"type":"string","description":"startup: the account was accepted to Runtime for Startups."},"grantedAt":{"type":"string","description":"When it was given, ISO 8601 UTC."},"expiresAt":{"type":"string","description":"12 months after grantedAt, ISO 8601 UTC: what is left then is gone."}}},"description":"Renamed startupIncluded; works until 30 days after the rename ships (date set at deploy), then is gone.","deprecated":true},"potLimits":{"type":["object","null"],"description":"Renamed startupLimits; works until 30 days after the rename ships (date set at deploy), then is gone.","properties":{"buildsAtOnce":{"type":"integer","minimum":1},"sandboxesAtOnce":{"type":"integer","minimum":1}},"required":["buildsAtOnce","sandboxesAtOnce"],"additionalProperties":false,"deprecated":true},"pilot":{"type":["object","null"],"description":"The account's pilot, while it serves its sandboxes, or null: a pilot is a free run agreed with Runtime. hours is its included time in sandbox-hours (running time of every pilot sandbox, whatever its size; paused and stopped time does not count); usedMs and leftMs are that time used and left, in milliseconds. Once it is used, its running sandboxes pause with their memory kept, and creates and wakes answer pilot_hours_used; to extend the pilot or ask for more hours, the account's owner writes to support.","properties":{"id":{"type":"string"},"sandboxes":{"type":"integer","minimum":1},"vcpu":{"type":"integer","minimum":1},"memoryMiB":{"type":"integer","minimum":1},"diskMiB":{"type":"integer","minimum":1},"startsAt":{"type":"string"},"endsAt":{"type":"string","description":"New pilot sandboxes until then, ISO 8601 UTC."},"graceEndsAt":{"type":"string","description":"The pilot's sandboxes are served, free, until then, ISO 8601 UTC."},"endedAt":{"type":["string","null"]},"hours":{"type":"integer","minimum":1},"usedMs":{"type":"integer","minimum":0},"leftMs":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0,"description":"Its sandboxes starting, running or resuming now, each using one sandbox-hour per hour: leftMs / running is how long the hours last at this rate."}}},"key":{"type":"object","description":"With ?key=<key id> only: that key's own spend, so a coordinator sees which worker spent what. A key may read itself, the keys it made (POST /v1/keys) at any depth, and any key whose agent its reads already reach (an account-wide or read-only key's).","properties":{"keyId":{"type":"string"},"agentId":{"type":"string","description":"The key's agent: what it made and spent is this agent's."},"name":{"type":"string"},"madeBy":{"type":["string","null"],"description":"The key that made it, if a key did."},"revokedAt":{"type":["string","null"]},"dailyLimitMicros":{"type":["string","null"],"pattern":"^[0-9]+$","description":"Its daily limit, in integer microdollars as a string, or null for none."},"dailyUsedMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"What it committed in the last 24 hours, as its daily limit counts: settled plus held. Integer microdollars, as a string."},"spentMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"Everything it has spent, settled. Integer microdollars, as a string."},"heldMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"What its running work holds now; settled as it is used. Integer microdollars, as a string."},"runningSandboxes":{"type":"integer","minimum":0},"resources":{"type":"integer","minimum":0,"description":"What it made that is not deleted: sandboxes, snapshots, volumes, images."}},"required":["keyId","agentId","name","madeBy","revokedAt","dailyLimitMicros","dailyUsedMicros","spentMicros","heldMicros","runningSandboxes","resources"]},"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"resources":{"type":"integer","minimum":0},"chargedMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"What its settled windows charged. Integer microdollars, as a string."},"heldMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"What its open windows hold. Integer microdollars, as a string."}},"required":["kind","resources","chargedMicros","heldMicros"],"additionalProperties":false},"description":"Everything this principal acts for, one row a kind, however many: how many resources, what was charged and what is held."},"resources":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"This principal's hundred newest resources and what each has used and been charged; kinds totals all of them."}},"required":["unit","credited","spent","held","expired","available","takenBack","resources"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account:close":{"post":{"operationId":"account.close","summary":"Close the account: stop and delete everything it runs and stores, end every key, and dissolve it.","description":"Needs a key for every product made by an owner, and confirm set to the account's name exactly (GET /v1/me shows it as orgName). It cannot be undone. Closing moves no money: what is unspent of a purchase made in the last 15 days is refunded by hand on request, as the terms say; other credit, and granted credit, is forfeited.","tags":["account"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","minLength":1,"maxLength":120,"description":"The account's name, typed exactly."}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string"},"name":{"type":"string","description":"The account's name, as it was typed to confirm."},"closedAt":{"type":"string","description":"When it closed, ISO 8601 UTC."},"released":{"type":"boolean","description":"True when nothing was left running or stored; otherwise what is still stopping is stopped and deleted within minutes."}},"required":["orgId","name","closedAt","released"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/emails":{"get":{"operationId":"account.emails","summary":"Which of Runtime's optional emails this key's person gets for this account.","description":"Each person chooses their own, per account: own-deletions, billing, usage and tips, each on until turned off. Sign-in, invitations, a revoked key, support replies, credit expiry, service credits and deletions Runtime decides are always sent and are not listed. A key acts for its person; a key with no person answers no_person.","tags":["account"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["own-deletions","billing","usage","tips"],"description":"own-deletions: deletion warnings for dates the account's own retention set; billing: credit running low or out; usage: the month's free usage at 80% and all; tips: getting-started emails."},"enabled":{"type":"boolean","description":"false: the email stops, for this person only."},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["category","enabled","updatedAt"],"additionalProperties":false}}},"required":["settings"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/account/emails:update":{"post":{"operationId":"account.emails.update","summary":"Turn one of Runtime's optional emails on or off for this key's person.","description":"Only the key's own person, in this account; the account's notices (GET /v1/notices) and webhooks are unchanged.","tags":["account"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["own-deletions","billing","usage","tips"]},"enabled":{"type":"boolean"}},"required":["category","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["own-deletions","billing","usage","tips"],"description":"own-deletions: deletion warnings for dates the account's own retention set; billing: credit running low or out; usage: the month's free usage at 80% and all; tips: getting-started emails."},"enabled":{"type":"boolean","description":"false: the email stops, for this person only."},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["category","enabled","updatedAt"],"additionalProperties":false}}},"required":["settings"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes":{"post":{"operationId":"sandboxes.create","summary":"Create a sandbox. Every field is optional.","description":"A Linux microVM with its own kernel and disk. With no body you get the free usage while the month has some left, the default region and a 2 vCPU / 4096 MiB / 4096 MiB machine that starts from a warm template. When no server has room it answers 409 no_capacity with Retry-After and charges nothing: retry with the same Idempotency-Key, which runs the create again (a refusal is never replayed). Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":32,"description":"Environment variables for every command, process, terminal, SSH session and the image's start command in this sandbox, under each command's own env. At most 32 variables and 32768 bytes of names and values. Values are never shown again: answers list only envNames."},"secrets":{"type":"array","items":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$"},"maxItems":64,"description":"The egress secrets this sandbox may use, by name, at most 64: it gets only those of your egress secrets (POST /v1/secrets) that would otherwise reach it, so a secret's own `only` still applies and is never widened. [] is none. Omit it for every secret that reaches it. A name with no secret yet is kept, and takes effect once you create that secret. Fixed for the sandbox's life; a fork or a copy of a snapshot keeps its source's list and may only narrow it. A sandbox outside a secret's list sees no placeholder for it, and its requests never carry the value."},"funding":{"type":"string","enum":["trial","paid"],"description":"Accepted and not read: the account decides. An account with prepaid credit (or a purchase it kept) runs paid sandboxes, which use the free usage first and then credit, with nothing to change; an account without credit runs sandboxes within the limits without credit."},"region":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,31}$","description":"Omit for the default region."},"vcpu":{"type":"integer","minimum":1,"maximum":16,"default":2,"description":"At most 16 (2 without credit)."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"default":4096,"description":"At most 65536, 64 GiB (4096 without credit)."},"diskMiB":{"type":"integer","minimum":3072,"maximum":409600,"default":4096,"description":"At least 3072; at most 409600, 400 GiB (10240 without credit)."},"cpu":{"type":"string","enum":["shared","reserved"],"default":"shared"},"cpuFloorMillis":{"type":"integer","minimum":1,"maximum":16000,"default":50,"description":"Guaranteed CPU in thousandths of a vCPU while shared. Reserved CPU guarantees all of it."},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"default":0,"description":"A time limit you choose, 60 to 86400 seconds (24 hours): the sandbox pauses (or stops, with onTimeout) when it runs out, busy or not, unless extended. Default 0, no limit: it runs while it works and pauses when idle (idlePauseSeconds), until you stop it or credit runs out. Without credit, the limit is capped at the free usage left."},"pausable":{"type":"boolean","deprecated":true,"description":"Ignored since 5 October 2026: every sandbox can pause."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pause the sandbox after this many seconds with no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes. Nothing is lost, and with autoWake the next request wakes it. Default 60 unless persistent; 0 is never; otherwise 10 to 86400."},"autoWake":{"type":"boolean","default":true,"description":"Wake the sandbox by itself when it is paused and a request needs it: an exec, a file, process, terminal or desktop call, or a visit to a shared port. It is billed as a wake from the moment it wakes. Default true."},"persistent":{"type":"boolean","default":false,"description":"Keep it running until you stop it, while credit lasts: no time limit even with timeoutSeconds, and no idle pause unless idlePauseSeconds asks for one. Its disk is billed as any sandbox's. Paid only."},"maxTotalCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"The most this sandbox may cost over its whole life, in microdollars; it stops there."},"getOrCreate":{"type":"boolean","default":false,"description":"With name: answer the sandbox that already has this name instead of refusing name_taken, waking it if paused and restarting it from its disk if stopped. The other fields apply only when it is created."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"default":"pause","description":"What happens when its timeoutSeconds, its credit or a spending limit ends it: pause (keep memory and files; wake later), stop (keep the files, billed as paused storage; restart later) or delete (when timeoutSeconds runs out, delete it and its files; credit or a spending limit only stops it). Default pause. onLeaseEnd, its older name, is accepted too."},"onLeaseEnd":{"type":"string","enum":["pause","stop","delete"],"description":"The older name of onTimeout, still accepted. Send one, or the same value in both."},"maxCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"Deprecated, still accepted from older clients: use maxTotalCostMicros."},"network":{"type":"object","properties":{"internet":{"type":"boolean","description":"false refuses every outbound connection."},"allow":{"type":"array","items":{"type":"string","maxLength":255,"description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range.","examples":["registry.npmjs.org","*.github.com","140.82.112.0/20"]},"maxItems":256,"description":"When not empty, only these destinations are reachable, on every port the sandbox may use."},"deny":{"type":"array","items":{"type":"string","maxLength":255,"description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range.","examples":["registry.npmjs.org","*.github.com","140.82.112.0/20"]},"maxItems":256,"description":"Never reachable. Wins over everything."},"connect":{"type":"array","items":{"type":"string","maxLength":262,"description":"host:port beyond the web ports, reached as a TCP tunnel through the sandbox's proxy: your own database, a git host over ssh.","examples":["db.example.com:5432","github.com:22","203.0.113.7:6379"]},"maxItems":64,"description":"host:port pairs beyond ports 80 and 443. A paid sandbox of an organization with a paid purchase reaches every port already; list pairs here when you narrow it with allow. Sandboxes without credit stay on ports 80 and 443."}},"required":["internet"],"additionalProperties":false,"description":"Network rules from the first start, the same shape as PUT /v1/sandboxes/{id}/network. Omit for the default: the public web on ports 80 and 443."},"image":{"type":"string","maxLength":300,"description":"Start from this ready image: its id, name (its latest tag), name:tag or name@version (POST /v1/images, runtime images build). The sandbox runs on the host that keeps it. When the image has a start command, create answers once its ready check passes, and says how in start."},"snapshot":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Start as a copy of this ready snapshot (POST /v1/sandboxes/{id}:snapshot), on a server that holds it: the one it was taken on, or one holding a checked copy of it. A memory snapshot's copy continues its files, memory and running processes, and is the snapshot's size: another size is refused. A disk snapshot's copy boots afresh with its files, at the vcpu, memoryMiB and diskMiB you ask (the snapshot's for what you leave out), with a disk at least the saved one. Not with image."},"tailscale":{"type":"object","properties":{"authKeySecret":{"type":"string","description":"The name of a job secret holding a Tailscale auth key (runtime secrets set NAME --jobs). Use an ephemeral, tagged key; a reusable one lets the sandbox log in again by itself after a long pause.","examples":["TS_AUTHKEY"]},"hostname":{"type":"string","description":"The machine's name on the tailnet, a DNS label. Default: the sandbox's name, or runtime- and its id's first eight characters."},"tags":{"type":"array","items":{"type":"string","examples":["tag:ci"]},"maxItems":16,"description":"Tailscale tags to advertise; the key must be allowed them."}},"required":["authKeySecret"],"additionalProperties":false,"description":"Join your Tailscale network once running; paid sandboxes only."},"volumes":{"type":"array","items":{"type":"object","properties":{"volumeId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"path":{"type":"string","pattern":"^(/[A-Za-z0-9._-]+)+$","maxLength":256,"description":"Where it is mounted, such as /data. Not under /etc, /usr, /proc and the like."},"mode":{"type":"string","enum":["rw","snapshot"],"default":"rw","description":"rw: read-write, one sandbox at a time. snapshot: a read-only copy as it is now, for any number of sandboxes."}},"required":["volumeId","path"],"additionalProperties":false},"maxItems":4,"description":"Volumes to attach at start (POST /v1/volumes), on the same host as the sandbox."},"spreadFrom":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":16,"description":"Ids of your sandboxes or snapshots, 1 to 16: this one starts on a server none of them is on, and stays apart if its start is moved. Use it to keep warm sources on separate servers, so copies of their snapshots start on several. Compare placement to check. When no other server has room, the create answers no_capacity and nothing is made. A copy of a snapshot can start only where that snapshot is kept."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"sandboxes.list","summary":"List sandboxes, oldest first. Live ones only unless you ask.","tags":["sandboxes"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque cursor from the previous page's nextCursor."},"description":"Opaque cursor from the previous page's nextCursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"description":"Repeat to match any of several states."},"description":"Repeat to match any of several states."},{"name":"includeStopped","in":"query","required":false,"schema":{"type":"boolean","description":"Include every stopped sandbox (default false: only a stopped one that keeps its disk, diskKept, is listed)."},"description":"Include every stopped sandbox (default false: only a stopped one that keeps its disk, diskKept, is listed)."},{"name":"label","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","maxLength":300},"description":"key:value; repeat to require several."},"description":"key:value; repeat to require several."},{"name":"name","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}":{"get":{"operationId":"sandboxes.get","summary":"Read one sandbox.","description":"Add waitFor=running (or paused, stopped) and timeoutSeconds to hold the answer until it gets there.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"waitFor","in":"query","required":false,"schema":{"type":"string","enum":["running","paused","stopped"]}},{"name":"timeoutSeconds","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":120}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"sandboxes.delete","summary":"Delete a sandbox: stop it, delete its disk and paused memory, revoke its previews and ports, and remove it from lists.","description":"Works in any state. Billing ends as a stop's does; a kept disk is billed until its host confirms the deletion, usually seconds. Its snapshots stay (delete them apart), and its usage, charges and audit entries stay. After it the sandbox reads nowhere: GET answers not_found. Deleting it again answers the same.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","const":"deleted"},"state":{"type":"string","description":"stopping until its machine has stopped, usually well under a second; then stopped."},"deletedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"replayed":{"type":"boolean"}},"required":["id","kind","status","state","deletedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:stop":{"post":{"operationId":"sandboxes.stop","summary":"Stop a sandbox and end its compute charges. Its disk is gone unless it was kept.","description":"Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:pause":{"post":{"operationId":"sandboxes.pause","summary":"Pause: memory and disk are saved, CPU and memory go back, compute charges end.","description":"Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:wake":{"post":{"operationId":"sandboxes.wake","summary":"Wake a paused sandbox on its own machine, carrying on where it paused.","description":"Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do. For a sandbox with a time limit, timeoutSeconds sets the new one; the default is its own, and without credit it is capped at the free usage left. One with no time limit keeps none.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timeoutSeconds":{"type":"integer","minimum":60,"maximum":86400}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:switch-image":{"post":{"operationId":"sandboxes.switchImage","summary":"Move a sandbox to another image, keeping its /workspace, id, name, volumes, environment and previews. Processes restart.","description":"Works on a running sandbox (paused first), a paused one, or a stopped one. It keeps /workspace (your home: dotfiles, pip --user and npm -g installs), volumes, environment, labels, name, previews and ports. It loses everything else on the old disk (sudo installs into /usr/local, apt packages, /etc edits) and every running process. Snapshot it first to keep everything. Charged as a wake. If anything fails the switch is undone and the sandbox stays on its old image with nothing lost (switch_undone). Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The image to move to: its id, name (its latest tag), name:tag or name@version. It must be ready, on the sandbox's server, and fit its disk."},"keep":{"type":"string","const":"workspace","description":"Optional, and only \"workspace\", which older clients send: a switch always keeps /workspace alone. It keeps /workspace (your home: dotfiles, pip --user and npm -g installs), volumes, environment, labels, name, previews and ports. It loses everything else on the old disk (sudo installs into /usr/local, apt packages, /etc edits) and every running process."}},"required":["image"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:resize":{"post":{"operationId":"sandboxes.resize","summary":"Change a sandbox's vCPUs, memory or disk by restarting it, keeping its whole disk. Running programs stop.","description":"Works on a running sandbox (stopped first if persistent, paused first otherwise), a paused one, or a stopped one. It keeps the whole disk (every file, installed package and setting), volumes, environment, labels, name, previews and ports. Every running program stops: a running sandbox is stopped first, and a paused one's saved memory is discarded, so it starts fresh from its disk. It stays on its server: no_capacity means that server has no room for the new size now, and nothing changed. A disk only grows (disk_shrink otherwise), and its filesystem fills the new size at the restart. Charged as a wake or a restart, at the new size and the same rates. Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vcpu":{"type":"integer","minimum":1,"maximum":16,"description":"The new number of vCPUs, 1 to 16 (without credit at most 2). Omit to keep it."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"description":"The new memory in MiB, 128 to 65536 (without credit at most 4096). Omit to keep it."},"diskMiB":{"type":"integer","minimum":3072,"maximum":409600,"description":"The new disk in MiB: only larger than it is, at most 409600 (without credit at most 10240). Its filesystem grows to fill it at the restart; a disk never shrinks. Omit to keep it."},"restart":{"type":"boolean","const":true,"description":"Optional, and only true, which older clients send: a resize always restarts the sandbox. It keeps the whole disk (every file, installed package and setting), volumes, environment, labels, name, previews and ports. Every running program stops: a running sandbox is stopped first, and a paused one's saved memory is discarded, so it starts fresh from its disk."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:extend":{"post":{"operationId":"sandboxes.extend","summary":"Give a sandbox with a time limit more time: its end moves this many seconds later.","description":"Never more than 24 hours ahead of now; endsAt answers the new end. Paid time is funded an hour at a time as it runs; without credit it runs on only while the free usage lasts. A sandbox with no time limit needs none: the call answers at once and changes nothing.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seconds":{"type":"integer","minimum":1,"maximum":86400}},"required":["seconds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:retention":{"post":{"operationId":"sandboxes.retention","summary":"How long a paused or stopped sandbox is kept: while your account has credit, or 1 to 365 days.","description":"By default (days: null) it is kept as long as your account has credit. Days count from the current pause. Paused storage is billed at its quoted rate; without credit it is kept seven days free. When credit runs out it is kept seven more days, and a notice always comes first.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":["integer","null"],"minimum":1,"maximum":365}},"required":["days"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:restart":{"post":{"operationId":"sandboxes.restart","summary":"Start a stopped sandbox again from its kept disk (memory is not kept; wake is for paused ones).","description":"Send `Prefer: wait=N` (seconds, at most 120) to get the answer once the sandbox has settled; the SDKs do.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:update":{"post":{"operationId":"sandboxes.update","summary":"Change a sandbox's name, labels, environment, automatic wake, idle pause, time limit, end action or persistence. Fields left out stay as they are.","description":"idlePauseSeconds set here (10 to 86400) counts from the last activity: a request, a running command or terminal, an open connection, network traffic or CPU use; 0 turns idle pause off. persistent: true keeps the sandbox running until you stop it, while credit lasts, with no idle pause or time limit, its disk billed as any sandbox's; paid sandboxes only. timeoutSeconds sets its time limit from now, sooner or later than before (0 removes it), and onTimeout what its end does: endsAt answers the new end. A change of end action that reaches the server's last paid stretch can end it up to about two minutes after the asked end, never before.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"secrets":{"type":"array","items":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$"},"maxItems":64,"description":"Refused: a sandbox's egress secrets are fixed when it is created. Create a new sandbox, or fork this one with a narrower list."},"env":{"type":"object","additionalProperties":{"type":["string","null"],"maxLength":32768},"maxProperties":64,"description":"Change its environment: a value sets a variable, null removes it; the rest stay. Commands started after the change get it; running ones keep what they started with. At most 32 variables and 32768 bytes in all."},"tailscale":{"type":["object","null"],"properties":{"authKeySecret":{"type":"string","description":"The name of a job secret holding a Tailscale auth key (runtime secrets set NAME --jobs). Use an ephemeral, tagged key; a reusable one lets the sandbox log in again by itself after a long pause.","examples":["TS_AUTHKEY"]},"hostname":{"type":"string","description":"The machine's name on the tailnet, a DNS label. Default: the sandbox's name, or runtime- and its id's first eight characters."},"tags":{"type":"array","items":{"type":"string","examples":["tag:ci"]},"maxItems":16,"description":"Tailscale tags to advertise; the key must be allowed them."}},"required":["authKeySecret"],"additionalProperties":false,"description":"Join your Tailscale network now (paid sandboxes only), or null to leave it."},"autoWake":{"type":"boolean","description":"Wake it by itself when it is paused and a request needs it (an exec, a file or terminal call, or a visit to a shared port)."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pause it after this many seconds with no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes, counted from now. 0 is never; otherwise 10 to 86400."},"persistent":{"type":"boolean","description":"Keep it running until you stop it, while credit lasts: no time limit even with timeoutSeconds, and no idle pause unless idlePauseSeconds asks for one. Its disk is billed as any sandbox's. Paid only."},"maxTotalCostMicros":{"type":["integer","null"],"minimum":1,"maximum":1000000000000,"description":"The most it may cost over its whole life, in microdollars; null removes the cap."},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"A new time limit, counted from now: 60 to 86400 seconds, sooner or later than the one it had, and it then ends as onTimeout says; a paused sandbox counts it from its next wake. 0 takes the limit away: it runs while it works and pauses when idle. Not for a persistent sandbox."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its timeoutSeconds, its credit or a spending limit ends it: pause (keep memory and files; wake later), stop (keep the files, billed as paused storage; restart later) or delete (when timeoutSeconds runs out, delete it and its files; credit or a spending limit only stops it). Default pause. onLeaseEnd, its older name, is accepted too. Changed for its next end."},"onLeaseEnd":{"type":"string","enum":["pause","stop","delete"],"description":"onTimeout's older name."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:fork":{"post":{"operationId":"sandboxes.fork","summary":"Copies of a sandbox as it is now: files, memory and running processes.","description":"A running sandbox is paused for the moment it takes to snapshot it (usually well under a second), then woken again. Answers once the copies are running: {sandboxes, snapshot}, where snapshot is null unless keepSnapshot. Each copy has the source's vCPUs, memory, disk and CPU (cpu and cpuFloorMillis), is quoted as a create with them would be, and runs on its host. A fork that fails after its snapshot is taken answers with the failing step's error; details.startedSandboxIds names the copies that did start, which keep running until stopped.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"How many copies: 1 to 100 on prepaid credit, 1 to 4 without credit. One fork takes at most a quarter of its server's free memory."},"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"secrets":{"type":"array","items":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$"},"maxItems":64,"description":"The egress secrets the copies may use: a narrower list than the source's. Omit it and each copy keeps the source's list (every secret that reaches it, when the source names none). A name the source may not use is refused."},"keepSnapshot":{"type":"boolean","default":false,"description":"Keep the snapshot the copies started from, to start more later (it is billed as snapshot storage). By default it is deleted when the fork ends, whether every copy started or not, and nothing is billed for it."},"funding":{"type":"string","enum":["trial","paid"],"description":"Accepted and not read: copies run on what the account's new sandboxes run on, as for a create. On an account without credit, each copy must fit the limits without credit (it has the source's size) and takes one of its running slots."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"kind":{"type":"string","const":"sandbox"},"name":{"type":["string","null"]},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"status":{"type":"string","enum":["pending","active","paused","stopping","stopped"],"description":"Deprecated: read state. An older, coarser name for it, kept for older clients."},"state":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]},"region":{"type":"string"},"funding":{"type":"string","enum":["trial","paid"]},"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"cpu":{"type":"string","enum":["shared","reserved"]},"cpuFloorMillis":{"type":"integer"},"pausable":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity."},"autoWake":{"type":"boolean","description":"A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port."},"persistent":{"type":"boolean","description":"It has no time limit and is not paused for being idle unless idlePauseSeconds says so."},"diskKept":{"type":"boolean","description":"Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused)."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time","description":"When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended."},"expiresAt":{"type":"string","format":"date-time","description":"Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself."},"endsAt":{"type":["string","null"],"format":"date-time","description":"When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"],"description":"When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit."},"memoryRestored":{"type":"boolean"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed."},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Deprecated, kept for older clients: read chargedMicros and GET /v1/usage."},"rates":{"type":"object"},"envNames":{"type":"array","items":{"type":"string"},"description":"The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown."},"secrets":{"type":["array","null"],"items":{"type":"string"},"description":"The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox."},"secretsEnforced":{"type":"boolean","description":"On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds."},"simulated":{"type":"boolean"},"replayed":{"type":"boolean","description":"Present and true when an Idempotency-Key replay answered."}},"required":["id","kind","status","state","region","funding","createdAt","expiresAt"],"additionalProperties":true}},"snapshot":{"type":["object","null"]}},"required":["sandboxes","snapshot"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:exec":{"post":{"operationId":"sandboxes.exec","summary":"Run a command and get its exit code and output.","description":"Waits for a sandbox that is still starting. A timeout is a result (timedOut: true, exitCode null, the output so far), never an error. For live output send `Accept: application/x-ndjson` (or stream: true): one JSON event per line, start / stdout / stderr / exit; a `continue` event gives the cursor to resume with GET .../processes/{processId}/output?follow=true. Retrying with the same Idempotency-Key never runs the command twice.","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","minLength":1,"maxLength":16384,"description":"A shell command, run as `bash -c \"<command>\"`: pipes, &&, redirection and globs work."},"argv":{"type":"array","items":{"type":"string","maxLength":16384},"minItems":1,"maxItems":128,"description":"Or the program and its arguments, run without a shell."},"cwd":{"type":"string","maxLength":4096,"description":"Working directory. Default /workspace."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back."},"stdin":{"type":"string","maxLength":1048576,"description":"Text given to the command's standard input, which is then closed."},"stdinBase64":{"type":"string","maxLength":1400000,"description":"Bytes for standard input, base64."},"user":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Who runs it: the sandbox user (uid 1000, HOME=/workspace), or root, through the sandbox's passwordless sudo with the same environment and PATH and HOME=/root. Saves prefixing every command with sudo."},"timeoutMs":{"type":"integer","minimum":1,"maximum":86400000,"default":60000,"description":"Default 60 s; up to 24 h."},"stream":{"type":"boolean","description":"Same as Accept: application/x-ndjson."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"exitCode":{"type":["integer","null"],"description":"null when the command did not exit by itself (timedOut)."},"stdout":{"type":"string"},"stderr":{"type":"string"},"timedOut":{"type":"boolean"},"stdoutTruncated":{"type":"boolean"},"stderrTruncated":{"type":"boolean"},"durationMs":{"type":["integer","null"]},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["exitCode","stdout","stderr","timedOut"],"additionalProperties":true}},"application/x-ndjson":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["start","stdout","stderr","exit","truncated","continue","error"]},"processId":{"type":"string","description":"start and continue."},"data":{"type":"string","description":"stdout and stderr: the text."},"base64":{"type":"string","description":"Lossless bytes when the process uses outputEncoding base64."},"offset":{"type":"integer","minimum":0,"description":"stdout and stderr: where the text begins."},"exitCode":{"type":["integer","null"],"description":"exit."},"state":{"type":"string","description":"exit."},"timedOut":{"type":"boolean","description":"exit."},"durationMs":{"type":"integer","minimum":0,"description":"exit."},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."},"droppedBytes":{"type":"integer","minimum":0,"description":"truncated: output lost before the cursor."},"resumeAt":{"type":"integer","minimum":0,"description":"truncated: the next byte kept."},"cursor":{"type":"integer","minimum":0,"description":"continue: follow /output with this cursor to resume."},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":[],"additionalProperties":false}},"required":["type"],"additionalProperties":false,"description":"One event per line. start, then stdout and stderr as they happen, then exit. continue means the stream reached its time limit: resume at cursor."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes":{"post":{"operationId":"processes.start","summary":"Start a background process: a server, a watcher, a long build, an interactive program.","description":"Returns at once with the process. stdinMode 'pipe' keeps standard input open for :write; pty gives it a terminal (and implies input). At most 16 run at once per sandbox.","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"command":{"type":"string","minLength":1,"maxLength":16384,"description":"A shell command, run as `bash -c \"<command>\"`: pipes, &&, redirection and globs work."},"argv":{"type":"array","items":{"type":"string","maxLength":16384},"minItems":1,"maxItems":128,"description":"Or the program and its arguments, run without a shell."},"cwd":{"type":"string","maxLength":4096,"description":"Working directory. Default /workspace."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back."},"stdin":{"type":"string","maxLength":1048576,"description":"Text given to the command's standard input, which is then closed."},"stdinBase64":{"type":"string","maxLength":1400000,"description":"Bytes for standard input, base64."},"user":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Who runs it: the sandbox user (uid 1000, HOME=/workspace), or root, through the sandbox's passwordless sudo with the same environment and PATH and HOME=/root. Saves prefixing every command with sudo."},"timeoutMs":{"type":"integer","minimum":1,"maximum":86400000,"description":"Kill it after this long. Default: runs until it exits or the sandbox stops."},"stdinMode":{"type":"string","enum":["closed","pipe"],"default":"closed"},"outputEncoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"},"pty":{"type":"object","properties":{"cols":{"type":"integer","minimum":1,"maximum":1000},"rows":{"type":"integer","minimum":1,"maximum":1000}},"required":[],"additionalProperties":false}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"processes.list","summary":"List running and recently finished processes (the last 16 finished are kept).","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes/{processId}":{"get":{"operationId":"processes.get","summary":"Read a process's state and exit code.","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"processId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes/{processId}/output":{"get":{"operationId":"processes.output","summary":"Read output after a cursor, or follow it live.","description":"JSON: chunks after cursor, nextCursor to pass next time, and the process. waitMs (up to 8000) holds the call until there is output. follow=true streams NDJSON events until exit. The latest 1 MiB is kept; truncated says when the cursor fell behind.","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"processId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"waitMs","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":8000}},{"name":"maxBytes","in":"query","required":false,"schema":{"type":"integer","minimum":4096,"maximum":196608}},{"name":"follow","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"stream":{"type":"string","enum":["stdout","stderr"]},"text":{"type":"string"},"base64":{"type":"string"},"offset":{"type":"integer","minimum":0}},"required":[],"additionalProperties":false}},"nextCursor":{"type":"integer","minimum":0,"description":"Pass as cursor next time."},"truncated":{"type":"boolean"},"droppedBytes":{"type":"integer","minimum":0},"process":{"type":["object","null"],"properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}},"required":["chunks","nextCursor","truncated","process"],"additionalProperties":false}},"application/x-ndjson":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["start","stdout","stderr","exit","truncated","continue","error"]},"processId":{"type":"string","description":"start and continue."},"data":{"type":"string","description":"stdout and stderr: the text."},"base64":{"type":"string","description":"Lossless bytes when the process uses outputEncoding base64."},"offset":{"type":"integer","minimum":0,"description":"stdout and stderr: where the text begins."},"exitCode":{"type":["integer","null"],"description":"exit."},"state":{"type":"string","description":"exit."},"timedOut":{"type":"boolean","description":"exit."},"durationMs":{"type":"integer","minimum":0,"description":"exit."},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."},"droppedBytes":{"type":"integer","minimum":0,"description":"truncated: output lost before the cursor."},"resumeAt":{"type":"integer","minimum":0,"description":"truncated: the next byte kept."},"cursor":{"type":"integer","minimum":0,"description":"continue: follow /output with this cursor to resume."},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":[],"additionalProperties":false}},"required":["type"],"additionalProperties":false,"description":"One event per line. start, then stdout and stderr as they happen, then exit. continue means the stream reached its time limit: resume at cursor."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes/{processId}:write":{"post":{"operationId":"processes.write","summary":"Send input to a process started with stdinMode 'pipe' or a pty.","description":"offset is how many input bytes you have sent before this call (stdinOffset on the process); a resend after a lost reply is then skipped, never typed twice. Omit it to append. eof closes the input (sends ^D to a terminal).","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"processId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","maxLength":1048576},"base64":{"type":"string","maxLength":1400000},"offset":{"type":"integer","minimum":0},"eof":{"type":"boolean"}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"process":{"type":["object","null"],"properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}},"required":["offset","process"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes/{processId}:signal":{"post":{"operationId":"processes.signal","summary":"Signal a process: SIGTERM (default), SIGINT, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2 or SIGKILL (the whole tree).","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"processId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signal":{"type":"string","enum":["SIGINT","SIGTERM","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2","SIGKILL"]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":["object","null"],"properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/processes/{processId}:resize":{"post":{"operationId":"processes.resize","summary":"Resize a process's terminal.","tags":["commands"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"processId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cols":{"type":"integer","minimum":1,"maximum":1000},"rows":{"type":"integer","minimum":1,"maximum":1000}},"required":["cols","rows"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":["object","null"],"properties":{"id":{"type":"string"},"kind":{"type":"string","const":"process"},"state":{"type":"string","enum":["running","exited","killed","timed_out","unknown"]},"exitCode":{"type":["integer","null"]},"command":{"type":"string"},"user":{"type":"string","enum":["sandbox","root"],"description":"Who it runs as."},"cwd":{"type":"string"},"pty":{"type":"boolean"},"outputEncoding":{"type":"string","enum":["utf8","base64"]},"stdinOpen":{"type":"boolean","description":"Input is still open for :write."},"stdinOffset":{"type":"integer","minimum":0,"description":"Bytes of input accepted so far."},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"timeoutMs":{"type":["integer","null"]},"outputBytes":{"type":"integer","minimum":0},"firstOffset":{"type":"integer","minimum":0,"description":"The oldest byte still kept."},"replayed":{"type":"boolean"},"outOfMemory":{"type":"object","properties":{"code":{"type":"string","const":"out_of_memory"},"processesKilled":{"type":"integer","minimum":1,"description":"Processes of this command the out-of-memory killer ended."},"memoryMiB":{"type":["integer","null"],"description":"The sandbox's memory size."},"message":{"type":"string"},"hint":{"type":"string","description":"What to do: a larger memoryMiB, or a program that uses less."}},"required":["code","processesKilled","memoryMiB","message","hint"],"additionalProperties":false,"description":"Present only when the sandbox ran out of memory and Linux's out-of-memory killer ended the program or something it started. The exit code alone (-9, or 137 from a shell) does not say why."}},"required":["id","kind","state","exitCode","command","startedAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/content":{"get":{"operationId":"files.read","summary":"Download a file's bytes, any size.","description":"Small files come in one read with an x-content-sha256 header. Large ones stream, read in parallel, checked against the file's digest at the end: a file that changes mid-read breaks the stream rather than arriving half old.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"files.write","summary":"Write a file of up to 1 MiB from the raw request body. Parent directories are made.","description":"Atomic: readers see the old file or the new one. Larger files: POST .../uploads (the SDKs switch for you).","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-7]{3,4}$","examples":["755"],"description":"Octal permissions for the file, e.g. 755 for a program. Default 644. No set-id or sticky bits."},"description":"Octal permissions for the file, e.g. 755 for a program. Default 644. No set-id or sticky bits."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"integer","minimum":0},"sha256":{"type":"string"}},"required":["path","size","sha256"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/list":{"get":{"operationId":"files.list","summary":"List a directory: names, types, sizes, modes, times. Optionally deep, optionally by glob.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":1000}},{"name":"hidden","in":"query","required":false,"schema":{"type":"boolean","default":true,"description":"Include dotfiles."},"description":"Include dotfiles."},{"name":"glob","in":"query","required":false,"schema":{"type":"string","maxLength":512,"description":"e.g. **/*.py, src/*.{ts,tsx}; relative to path."},"description":"e.g. **/*.py, src/*.{ts,tsx}; relative to path."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"type":{"type":"string","enum":["file","directory","symlink","other"]},"size":{"type":"integer","minimum":0},"mode":{"type":"string","description":"Octal permissions, e.g. 0644."},"modifiedAt":{"type":"string","format":"date-time"},"uid":{"type":"integer","minimum":0},"gid":{"type":"integer","minimum":0},"owner":{"type":"string"},"group":{"type":"string"},"symlinkTarget":{"type":"string"}},"required":["name","path","type","size","mode","modifiedAt"],"additionalProperties":false}},"truncated":{"type":"boolean","description":"There were more entries than limit."},"nextCursor":{"type":"null"}},"required":["data","truncated","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/stat":{"get":{"operationId":"files.stat","summary":"Does a path exist, and what is it. Never follows a final link.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"exists":{"type":"boolean","const":false},"path":{"type":"string"}},"required":["exists","path"],"additionalProperties":false},{"type":"object","properties":{"exists":{"type":"boolean","const":true},"name":{"type":"string"},"path":{"type":"string"},"type":{"type":"string","enum":["file","directory","symlink","other"]},"size":{"type":"integer","minimum":0},"mode":{"type":"string","description":"Octal permissions, e.g. 0644."},"modifiedAt":{"type":"string","format":"date-time"},"uid":{"type":"integer","minimum":0},"gid":{"type":"integer","minimum":0},"owner":{"type":"string"},"group":{"type":"string"},"symlinkTarget":{"type":"string"}},"required":["exists","name","path","type","size","mode","modifiedAt"],"additionalProperties":false}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files:mkdir":{"post":{"operationId":"files.mkdir","summary":"Make a directory (and its parents, by default). An existing one is success.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"parents":{"type":"boolean","default":true}},"required":["path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"created":{"type":"boolean"}},"required":["path","created"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files:remove":{"post":{"operationId":"files.remove","summary":"Remove a file, a link or a directory (recursive for one with contents). Missing is success.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"recursive":{"type":"boolean","default":false}},"required":["path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"removed":{"type":"boolean"}},"required":["path","removed"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files:rename":{"post":{"operationId":"files.rename","summary":"Move or rename. Refuses to replace an existing path unless overwrite.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"to":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"overwrite":{"type":"boolean","default":false}},"required":["from","to"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"replayed":{"type":"boolean"}},"required":["from","to"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files:chmod":{"post":{"operationId":"files.chmod","summary":"Set a file's permissions, e.g. 755 to make it runnable.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"mode":{"type":"string","pattern":"^[0-7]{3,4}$","examples":["755"],"description":"Octal permissions for the file, e.g. 755 for a program. Default 644. No set-id or sticky bits."}},"required":["path","mode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"mode":{"type":"string"}},"required":["path","mode"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/uploads":{"post":{"operationId":"files.uploadBegin","summary":"Begin a large upload into /workspace: declare the size and SHA-256.","description":"Then PUT each 1 MiB chunk (offset a multiple of chunkBytes; the last may be shorter), in any order and several at once, and commit. The file appears atomically only if every byte matches the digest.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"Absolute path under /workspace, e.g. /workspace/data/model.bin. To place the file elsewhere, move it with exec after the commit."},"size":{"type":"integer","minimum":0},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"mode":{"type":"string","pattern":"^[0-7]{3,4}$","examples":["755"],"description":"Octal permissions for the file, e.g. 755 for a program. Default 644. No set-id or sticky bits."}},"required":["path","size","sha256"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"uploadId":{"type":"string"},"chunkBytes":{"type":"integer","minimum":1,"description":"Send chunks of this size."},"parallel":{"type":"boolean","description":"Chunks may be sent at the same time."},"replayed":{"type":"boolean"},"mode":{"type":"string","pattern":"^[0-7]{3,4}$","examples":["755"],"description":"Octal permissions for the file, e.g. 755 for a program. Default 644. No set-id or sticky bits."}},"required":["uploadId","chunkBytes"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/uploads/{uploadId}":{"put":{"operationId":"files.uploadChunk","summary":"Send one chunk of a large upload as the raw body.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^u-[a-f0-9]{32}$","description":"The uploadId begin returned."}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"integer","minimum":0},"replayed":{"type":"boolean"}},"required":["received"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/uploads/{uploadId}:commit":{"post":{"operationId":"files.uploadCommit","summary":"Finish an upload: the file appears only if size and SHA-256 match.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^u-[a-f0-9]{32}$","description":"The uploadId begin returned."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"size":{"type":"integer","minimum":0},"sha256":{"type":"string"},"replayed":{"type":"boolean"}},"required":["size","sha256"],"additionalProperties":false},{"type":"object","properties":{"aborted":{"type":"boolean","const":true}},"required":["aborted"],"additionalProperties":false}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/uploads/{uploadId}:abort":{"post":{"operationId":"files.uploadAbort","summary":"Discard an unfinished upload.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^u-[a-f0-9]{32}$","description":"The uploadId begin returned."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"size":{"type":"integer","minimum":0},"sha256":{"type":"string"},"replayed":{"type":"boolean"}},"required":["size","sha256"],"additionalProperties":false},{"type":"object","properties":{"aborted":{"type":"boolean","const":true}},"required":["aborted"],"additionalProperties":false}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/archive":{"get":{"operationId":"files.archive.download","summary":"Download a folder as a tar archive, streamed, any size.","description":"Packed by tar inside the sandbox and streamed as it is made: application/x-tar, or application/gzip with gzip=true. Entries are relative to the folder (./a.txt). A folder that fails part way (a file it may not read, one that changes as it is read) ends as an archive every tar reader refuses, never as a short one that looks whole. Needs read_file. Wakes a paused sandbox, as other file calls do. At most 4 at once in a sandbox.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"The folder, absolute, e.g. /workspace/app. An upload makes it and its parents, and merges into what is there."},"description":"The folder, absolute, e.g. /workspace/app. An upload makes it and its parents, and merges into what is there."},{"name":"gzip","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"Compress with gzip."},"description":"Compress with gzip."},{"name":"user","in":"query","required":false,"schema":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Run tar as the sandbox user, or as root through passwordless sudo."},"description":"Run tar as the sandbox user, or as root through passwordless sudo."},{"name":"exclude","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":32,"description":"Relative paths to leave out, such as .openai-agents-staging. Plain names only, no wildcards."},"description":"Relative paths to leave out, such as .openai-agents-staging. Plain names only, no wildcards."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/x-tar":{"schema":{"type":"string","contentMediaType":"application/x-tar"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"files.archive.upload","summary":"Unpack a tar archive of up to 1 MiB into a folder, from the raw request body.","description":"The folder and its parents are made; the archive merges into what is there, replacing files of the same name. gzip is recognised by its first bytes. Larger archives: POST .../files/archive/uploads (the SDKs switch for you). Needs write_file.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"path","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096,"description":"The folder, absolute, e.g. /workspace/app. An upload makes it and its parents, and merges into what is there."},"description":"The folder, absolute, e.g. /workspace/app. An upload makes it and its parents, and merges into what is there."},{"name":"user","in":"query","required":false,"schema":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Run tar as the sandbox user, or as root through passwordless sudo."},"description":"Run tar as the sandbox user, or as root through passwordless sudo."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"received":{"type":"integer","minimum":0,"description":"Bytes of archive unpacked."}},"required":["path","received"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/archive/uploads":{"post":{"operationId":"files.archive.uploadBegin","summary":"Begin unpacking a large tar archive into a folder, sent in chunks.","description":"Then PUT the archive in order, 1 MiB at most a request, at ?offset= its place, and commit. The sandbox unpacks as the bytes arrive, so nothing is staged on its disk. A chunk resent after a lost answer is not written twice. An upload not committed within 6 hours is ended. At most 4 at once in a sandbox. Needs write_file.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"The folder, absolute, e.g. /workspace/app. An upload makes it and its parents, and merges into what is there."},"gzip":{"type":"boolean","default":false,"description":"The archive is gzip-compressed."},"user":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Run tar as the sandbox user, or as root through passwordless sudo."}},"required":["path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"uploadId":{"type":"string","pattern":"^a-[a-f0-9]{32}$"},"path":{"type":"string"},"gzip":{"type":"boolean"},"chunkBytes":{"type":"integer","minimum":1}},"required":["uploadId","path","gzip","chunkBytes"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/archive/uploads/{uploadId}":{"put":{"operationId":"files.archive.uploadChunk","summary":"Send the next part of a folder upload as the raw body.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^a-[a-f0-9]{32}$","description":"The uploadId begin returned."}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Where this part starts."},"description":"Where this part starts."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"integer","minimum":0}},"required":["received"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/archive/uploads/{uploadId}:commit":{"post":{"operationId":"files.archive.uploadCommit","summary":"Finish a folder upload: answers once tar has unpacked it all.","description":"A commit repeated after it succeeded answers the same, while the sandbox still holds the finished tar (its last 16 processes).","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^a-[a-f0-9]{32}$","description":"The uploadId begin returned."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"received":{"type":"integer","minimum":0,"description":"Bytes of archive unpacked."}},"required":["path","received"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/archive/uploads/{uploadId}:abort":{"post":{"operationId":"files.archive.uploadAbort","summary":"Stop a folder upload. What was unpacked so far stays.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","pattern":"^a-[a-f0-9]{32}$","description":"The uploadId begin returned."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"aborted":{"type":"boolean","const":true}},"required":["aborted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/watches":{"post":{"operationId":"files.watches.create","summary":"Watch a file or directory for changes.","description":"Starts a watch in the sandbox and answers once it is watching, so nothing changed after the answer is missed. Read its events with GET .../watches/{watchId}/events (poll with a cursor, or follow=true for a stream). Default events are create, write, remove, rename (with oldPath) and chmod; access events are opt-in. Events are batched every batchMs with repeated writes folded into one event. A new directory under a recursive watch is scanned when it appears, so files made in it before its watch took effect are reported too. At most 4 watches per sandbox; each ends after timeoutMs, or runs until stopped when timeoutMs is zero. webhook: true also sends its changes to the account's webhooks as sandbox.files.changed events, so nothing has to read it. Needs the exec scope. Wakes a paused sandbox.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":4096,"description":"The directory to watch, absolute, e.g. /workspace/app."},"recursive":{"type":"boolean","description":"Watch every directory under it too. Default false."},"events":{"type":"array","items":{"type":"string","enum":["create","write","remove","rename","chmod","access"]},"minItems":1,"description":"Only these event types. Default: all of create, write, remove, rename, chmod."},"include":{"type":"array","items":{"type":"string","minLength":1,"maxLength":512},"maxItems":64,"description":"Report only paths matching one of these globs, relative to path (`**/*.py`; a bare `*.py` matches at any depth)."},"exclude":{"type":"array","items":{"type":"string","minLength":1,"maxLength":512},"maxItems":64,"description":"Skip paths matching these globs. A directory excluded (`node_modules`, `dist/**`) is not watched at all."},"batchMs":{"type":"integer","minimum":0,"maximum":5000,"description":"Gather events this long and send them as one batch, folding repeated writes to a file into one event with a count. Default 100."},"timeoutMs":{"type":"integer","minimum":0,"maximum":86400000,"description":"The watch ends by itself after running this long; 0 lasts until stopped or the sandbox ends. Default 3600000 (1 h)."},"maxWatches":{"type":"integer","minimum":1,"maximum":50000,"description":"Directories watched at most; past it a `limit` notice. Default 10000."},"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"A watch's id."},"webhook":{"type":"boolean","description":"Also send its changes to the account's webhooks as sandbox.files.changed events, read by Runtime without waking the sandbox: at most one event every 2 s a watch, 16 such watches an account. Default false."}},"required":["path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"processId":{"type":"string"},"state":{"type":"string"},"startedAt":{"type":"integer"},"cursor":{"type":"integer","minimum":0,"description":"Read events from here."},"watches":{"type":"integer","minimum":0,"description":"Directories being watched."},"webhook":{"type":"boolean","description":"Its changes go to the account's webhooks."}},"required":["id","path","processId","state"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"files.watches.list","summary":"The watches running in a sandbox.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"processId":{"type":"string"},"state":{"type":"string"},"startedAt":{"type":"integer"},"cursor":{"type":"integer","minimum":0,"description":"Read events from here."},"watches":{"type":"integer","minimum":0,"description":"Directories being watched."},"webhook":{"type":"boolean","description":"Its changes go to the account's webhooks."}},"required":["id","path","processId","state"],"additionalProperties":false}}},"required":["data"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/watches/{watchId}/events":{"get":{"operationId":"files.watches.events","summary":"A watch's events after a cursor, or follow them live.","description":"JSON: events after cursor, notices, nextCursor to pass next time, lostBytes when this reader fell more than 1 MiB behind (rescan), ended. waitMs (up to 8000) holds the call until something happens. follow=true (or Accept: application/x-ndjson) streams events until the watch ends; a stream ends with paused when the sandbox pauses (read again after it wakes: nothing is lost) or continue after 110 s, each with the cursor to resume from. Reading never wakes a paused sandbox.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"watchId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"A watch's id."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"waitMs","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":8000}},{"name":"follow","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["create","write","remove","rename","chmod","access"]},"path":{"type":"string"},"isDir":{"type":"boolean"},"oldPath":{"type":"string","description":"rename: where it was."},"count":{"type":"integer","minimum":1,"description":"write: writes folded into this event."}},"required":["type","path","isDir"],"additionalProperties":false}},"notices":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"overflow {dropped, reason: kernel|rate}: events were lost, rescan. limit {watches}: some directories are not watched. end {reason}: the watch stopped."},"nextCursor":{"type":"integer","minimum":0},"lostBytes":{"type":"integer","minimum":0,"description":"Events the sandbox discarded because this reader fell over 1 MiB behind."},"ended":{"type":"boolean"}},"required":["events","notices","nextCursor","lostBytes","ended"],"additionalProperties":false}},"application/x-ndjson":{"schema":{"type":"object","properties":{"k":{"type":"string","enum":["events","overflow","limit","lost","end","paused","continue","failure"]}},"required":["k"],"additionalProperties":true,"description":"One event per line. events {events, cursor}; overflow; limit; lost {bytes}; end {reason}; paused {cursor}: the sandbox paused, read again after it wakes; continue {cursor}: reconnect from here."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/files/watches/{watchId}":{"delete":{"operationId":"files.watches.delete","summary":"Stop a watch.","description":"Does not wake a paused sandbox: it answers 409 sandbox_not_running, unless the watch was sending to webhooks, which stops at once. A timed watch ends by its own timeout; an indefinite watch resumes with the sandbox.","tags":["files"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"watchId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"A watch's id."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"stopped":{"type":"boolean"}},"required":["stopped"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/feedback":{"post":{"operationId":"feedback.submit","summary":"Tell Runtime something: a bug, a missing feature, a gap against another provider, a migration blocker.","description":"Read by the team. Please report generously: small annoyances count. Quote the requestId of an error you hit. An account that has never added credit files 5 a day (429 rate_limited after).","tags":["feedback"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["bug","missing_feature","competitor_gap","migration_blocker","docs","pricing","praise","other"],"description":"bug | missing_feature | competitor_gap (something another provider does better) | migration_blocker (what stops a move to Runtime) | docs | pricing | praise | other"},"summary":{"type":"string","minLength":1,"maxLength":200,"description":"One line."},"detail":{"type":"string","maxLength":8000,"description":"What happened, what you expected, how to reproduce."},"competitor":{"type":"string","maxLength":80,"description":"E.g. E2B, Daytona, Modal, Vercel Sandbox."},"resourceId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"requestId":{"type":"string","maxLength":64,"pattern":"^req_[0-9a-z]{1,40}$","description":"From the error you are reporting."},"context":{"type":"object","description":"Anything else useful, at most 4 KB of JSON."}},"required":["kind","summary"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"duplicate":{"type":"boolean","description":"The same report was already filed."},"message":{"type":"string","description":"Received, and waiting to be sorted: triage runs every hour."}},"required":["id","duplicate"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"feedback.list","summary":"Your organization's reports, newest first, each with the status of the item it merged into.","description":"A report with sorted false and item null was received and is waiting to be sorted into an item; sorting runs every hour.","tags":["feedback"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","description":"new (also while unsorted), or the status of the item it merged into: planned, shipped, declined."},"sorted":{"type":"boolean","description":"False until the hourly triage puts the report into an item. Unsorted is received, not lost."},"note":{"type":"string","description":"The state in words, e.g. waiting to be sorted."},"item":{"type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"shippedNote":{"type":["string","null"]},"shippedAt":{"type":["string","null"],"format":"date-time"}}}},"required":["id","kind","summary","createdAt","status","sorted","note","item"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/support/messages":{"post":{"operationId":"support.message","summary":"Talk to Runtime support (an AI agent that can escalate to a person).","description":"Returns {conversationId, status: answered | working | escalated | waiting_customer | capped, reply?, pendingActions}. When status is working, read the conversation again in about a minute. Support proposes account actions; nothing runs until you send approveActionId with its approveInputHash.","tags":["support"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"From a previous reply."},"message":{"type":"string","minLength":1,"maxLength":8000},"approveActionId":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},"approveInputHash":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"denyActionId":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string"},"status":{"type":"string","enum":["answered","working","escalated","waiting_customer","capped"]},"reply":{"type":"string"},"pendingActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"inputHash":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","action","summary","inputHash"],"additionalProperties":true},"description":"Proposed account actions; nothing runs until one is approved."}},"required":["conversationId","status"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/support/conversations/{conversationId}":{"get":{"operationId":"support.read","summary":"Read a support conversation's latest state and reply.","tags":["support"],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"From a previous reply."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string"},"status":{"type":"string","enum":["answered","working","escalated","waiting_customer","capped"]},"reply":{"type":"string"},"pendingActions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"resourceId":{"type":"string"},"summary":{"type":"string"},"inputHash":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","action","summary","inputHash"],"additionalProperties":true},"description":"Proposed account actions; nothing runs until one is approved."}},"required":["conversationId","status"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/billing/auto-top-up":{"get":{"operationId":"billing.auto_top_up_get","summary":"Read auto top-up: the line, the amount, the monthly limit and the card.","description":"When the account's credit falls below `below`, its saved card is charged `amount` plus tax, at most once at a time and at most `monthlyLimit` a calendar month. Each automatic top-up that clears adds 5% more as credit. While it is on the account may run 200 sandboxes at once instead of 100. A declined charge, or one the bank wants its holder to confirm, turns it off; it never stops a running sandbox. A person saves the card at saveCardAt.","tags":["billing"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Charging now."},"waitingForCard":{"type":"boolean","description":"Asked to turn on; turns on once a card is saved at saveCardAt."},"below":{"type":["number","null"],"description":"Charge when credit falls below these dollars."},"amount":{"type":["number","null"],"description":"Dollars added each time, before tax."},"monthlyLimit":{"type":["number","null"],"description":"The most added in one calendar month (UTC), in dollars before tax."},"thisMonth":{"type":"number","description":"Dollars added this month, a charge in flight included."},"card":{"type":"boolean","description":"A card is saved for auto top-up."},"offReason":{"type":["string","null"],"description":"Why it turned itself off: declined, authentication_required (the bank wanted the holder), card_removed, no_address (no billing address for tax), blocked, failed. Null while on."},"offAt":{"type":["string","null"],"format":"date-time"},"saveCardAt":{"type":["string","null"],"description":"Where a person saves the card, when none is saved. Null once one is."}},"required":["enabled","waitingForCard","below","amount","monthlyLimit","thisMonth","card","offReason"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"billing.auto_top_up_set","summary":"Set auto top-up's three figures and turn it on or leave it off.","description":"When the account's credit falls below `below`, its saved card is charged `amount` plus tax, at most once at a time and at most `monthlyLimit` a calendar month. Each automatic top-up that clears adds 5% more as credit. While it is on the account may run 200 sandboxes at once instead of 100. A declined charge, or one the bank wants its holder to confirm, turns it off; it never stops a running sandbox. A person saves the card at saveCardAt. Owners, admins and billing members, and keys they made; not a read-only key.","tags":["billing"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true to turn on (once a card is saved), false to keep it off."},"below":{"type":"number","description":"Charge when credit falls below this, in whole cents: $10 at least. Left out, it keeps the one saved, or $10."},"amount":{"type":"number","description":"Dollars to add each time, before tax: $20 to $10,000, and at most $500 in an account's first week. Left out, it keeps the one saved, or $20."},"monthlyLimit":{"type":"number","description":"The most to add in one calendar month (UTC), before tax: $100 at least, and at least amount. Left out, it keeps the one saved, or $500."}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Charging now."},"waitingForCard":{"type":"boolean","description":"Asked to turn on; turns on once a card is saved at saveCardAt."},"below":{"type":["number","null"],"description":"Charge when credit falls below these dollars."},"amount":{"type":["number","null"],"description":"Dollars added each time, before tax."},"monthlyLimit":{"type":["number","null"],"description":"The most added in one calendar month (UTC), in dollars before tax."},"thisMonth":{"type":"number","description":"Dollars added this month, a charge in flight included."},"card":{"type":"boolean","description":"A card is saved for auto top-up."},"offReason":{"type":["string","null"],"description":"Why it turned itself off: declined, authentication_required (the bank wanted the holder), card_removed, no_address (no billing address for tax), blocked, failed. Null while on."},"offAt":{"type":["string","null"],"format":"date-time"},"saveCardAt":{"type":["string","null"],"description":"Where a person saves the card, when none is saved. Null once one is."}},"required":["enabled","waitingForCard","below","amount","monthlyLimit","thisMonth","card","offReason"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"billing.auto_top_up_off","summary":"Turn auto top-up off. The figures and the card are kept.","description":"A charge already sent still lands as credit, with its 5%. Running sandboxes are never stopped; above 100 at once, new ones wait until fewer than 100 run.","tags":["billing"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Charging now."},"waitingForCard":{"type":"boolean","description":"Asked to turn on; turns on once a card is saved at saveCardAt."},"below":{"type":["number","null"],"description":"Charge when credit falls below these dollars."},"amount":{"type":["number","null"],"description":"Dollars added each time, before tax."},"monthlyLimit":{"type":["number","null"],"description":"The most added in one calendar month (UTC), in dollars before tax."},"thisMonth":{"type":"number","description":"Dollars added this month, a charge in flight included."},"card":{"type":"boolean","description":"A card is saved for auto top-up."},"offReason":{"type":["string","null"],"description":"Why it turned itself off: declined, authentication_required (the bank wanted the holder), card_removed, no_address (no billing address for tax), blocked, failed. Null while on."},"offAt":{"type":["string","null"],"format":"date-time"},"saveCardAt":{"type":["string","null"],"description":"Where a person saves the card, when none is saved. Null once one is."}},"required":["enabled","waitingForCard","below","amount","monthlyLimit","thisMonth","card","offReason"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter:run":{"post":{"operationId":"interpreter.run","summary":"Run a cell of Python, JavaScript, TypeScript, R, Java, Bash or Go in a stateful context and return its results.","description":"Variables, imports and functions persist between calls to the same context, like a notebook (Go keeps declarations, not values: each Go cell is compiled with the functions, types and imports of earlier cells and run). Returns stdout, stderr, results (a MIME bundle each: text/plain, text/html, image/png as base64, image/svg+xml, text/markdown, application/json, application/vnd.runtime.table+json for a table), and an error with its traceback. matplotlib figures and R plots are returned as PNG images; a pandas DataFrame, an R data frame and a JavaScript array of objects as tables. In every language, `display` returns a file (.png .jpg .svg .html .md .json .txt, .csv as a table) as a result. A value larger than 48 KiB, and output beyond 256 KiB per stream, is written to a file in the sandbox and returned as a ref you can fetch with the result route. Needs the exec, write_file and read_file scopes. python3, node and bash are in the default image. R (r-base-core), Java (openjdk-21-jdk-headless) and Go (golang-go) are installed from the Ubuntu archive on a context's first start when the image lacks them, which takes tens of seconds once and needs the archive allowed by the sandbox's network rules.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","maxLength":524288,"description":"The cell to run."},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python by default. R, Java and Go are installed on first use (tens of seconds, once) when the image lacks them."},"context":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."},"timeoutMs":{"type":"integer","minimum":0,"maximum":3600000,"default":300000,"description":"Interrupt the cell after this long; 0 disables the cell deadline. The sandbox lease still applies. The context survives an interrupt; a cell that ignores it is killed 5 s later with its context."},"stream":{"type":"boolean","description":"Stream events as newline-delimited JSON (application/x-ndjson) while the cell runs, ending with the execution."},"interruptOnDisconnect":{"type":"boolean","default":true,"description":"Interrupt the cell when the caller disconnects. false detaches the reader and leaves the cell running under the sandbox's lease."}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"contextId":{"type":"string"},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"]},"executionCount":{"type":["integer","null"]},"status":{"type":"string","enum":["ok","error","interrupted","timeout","lost"]},"stdout":{"type":"string"},"stderr":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"main":{"type":"boolean","description":"The cell's own value, rather than a display."},"data":{"type":"object","description":"A MIME bundle: text/plain, image/png (base64)..."},"refs":{"type":"object","description":"Values too large to travel inline: fetch each with the results route."}},"required":["main","data","refs"],"additionalProperties":false}},"error":{"type":["object","null"],"properties":{"name":{"type":"string"},"value":{"type":"string"},"traceback":{"type":"string"}}},"durationMs":{"type":"integer","minimum":0}},"required":["id","contextId","language","status","stdout","stderr","results","error"],"additionalProperties":true}},"application/x-ndjson":{"schema":{"type":"object","properties":{"k":{"type":"string","enum":["start","stdout","stderr","result","error","end","execution","failure"]},"text":{"type":"string","description":"stdout and stderr."},"execution":{"type":"object","properties":{"id":{"type":"string"},"contextId":{"type":"string"},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"]},"executionCount":{"type":["integer","null"]},"status":{"type":"string","enum":["ok","error","interrupted","timeout","lost"]},"stdout":{"type":"string"},"stderr":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"main":{"type":"boolean","description":"The cell's own value, rather than a display."},"data":{"type":"object","description":"A MIME bundle: text/plain, image/png (base64)..."},"refs":{"type":"object","description":"Values too large to travel inline: fetch each with the results route."}},"required":["main","data","refs"],"additionalProperties":false}},"error":{"type":["object","null"],"properties":{"name":{"type":"string"},"value":{"type":"string"},"traceback":{"type":"string"}}},"durationMs":{"type":"integer","minimum":0}},"required":["id","contextId","language","status","stdout","stderr","results","error"],"additionalProperties":true,"description":"execution: the finished cell, last."}},"required":["k"],"additionalProperties":true,"description":"One event per line. stdout, stderr, result and error as they happen, then execution."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter/contexts":{"get":{"operationId":"interpreter.contexts.list","summary":"List the interpreter contexts running in a sandbox.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"language":{"type":"string"},"processId":{"type":"string"},"cwd":{"type":"string"},"state":{"type":"string"},"startedAt":{"type":"integer"}},"required":[],"additionalProperties":false}}},"required":["data"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"interpreter.contexts.create","summary":"Start an isolated interpreter context with its own state, directory and environment.","description":"At most 4 contexts run in one sandbox; each is a process of the sandbox's own user.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python by default. R, Java and Go are installed on first use (tens of seconds, once) when the image lacks them."},"cwd":{"type":"string","pattern":"^/workspace(/.*)?$"},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"maxProperties":64,"description":"Environment variables for the context's process."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"language":{"type":"string"},"processId":{"type":"string"},"cwd":{"type":"string"},"state":{"type":"string"},"startedAt":{"type":"integer"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter/contexts/{context}:restart":{"post":{"operationId":"interpreter.contexts.restart","summary":"Clear a context's state by starting its process again.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"context","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"env":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"maxProperties":64,"description":"Environment variables for the context's process."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"language":{"type":"string"},"processId":{"type":"string"},"cwd":{"type":"string"},"state":{"type":"string"},"startedAt":{"type":"integer"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter/contexts/{context}:interrupt":{"post":{"operationId":"interpreter.contexts.interrupt","summary":"Interrupt the running cell, like Ctrl-C. The context keeps its state.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"context","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"interrupted":{"type":"boolean"}},"required":["interrupted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter/contexts/{context}":{"delete":{"operationId":"interpreter.contexts.delete","summary":"Stop a context. Its memory is gone; its result files stay in the sandbox.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"context","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/interpreter/contexts/{context}/results/{file}":{"get":{"operationId":"interpreter.results.get","summary":"Download a result file a ref names: a large image, HTML page, table or overflowed output.","tags":["interpreter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"context","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id; each language's name is its default context, started on first use."}},{"name":"file","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$"}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/registries":{"get":{"operationId":"images.registries.list","summary":"Registries this organization stores credentials for. Secrets are never returned.","tags":["images"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"registry":{"type":"string"},"kind":{"type":"string","enum":["basic","ecr"]},"username":{"type":"string"},"region":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","registry","kind","username"],"additionalProperties":true}}},"required":["data"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"images.registries.set","summary":"Store credentials for pulling private images from a registry.","description":"Replaces any credentials stored for the same registry. The secret is sealed to Runtime's hosts the moment it arrives: the API can never read it back and no call returns it. A build opens it only to pull, inside its own build guest. For Amazon ECR, give an access key that may call ecr:GetAuthorizationToken and pull; each build asks ECR for a fresh token.","tags":["images"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"registry":{"type":"string","maxLength":253,"description":"The registry host: docker.io, ghcr.io, gcr.io, us-docker.pkg.dev, 123456789012.dkr.ecr.us-east-1.amazonaws.com, or any other."},"username":{"type":"string","maxLength":256,"description":"Docker Hub or GitHub user, oauth2accesstoken or _json_key for Google."},"password":{"type":"string","maxLength":65536,"description":"A token or password; for _json_key, the service account's JSON key."},"accessKeyId":{"type":"string","maxLength":128,"description":"Amazon ECR: an AWS access key id."},"secretAccessKey":{"type":"string","maxLength":256,"description":"Amazon ECR: its secret."}},"required":["registry"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"registry":{"type":"string"},"kind":{"type":"string","enum":["basic","ecr"]},"username":{"type":"string"},"region":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","registry","kind","username"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/registries:delete":{"post":{"operationId":"images.registries.delete","summary":"Forget the credentials stored for a registry.","tags":["images"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"registry":{"type":"string","maxLength":300}},"required":["registry"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"registry":{"type":"string"},"deleted":{"type":"boolean"}},"required":["registry","deleted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/context/missing":{"post":{"operationId":"images.context.missing","summary":"Which chunks of a build context still need uploading.","description":"Chunks already stored count as used, so they stay for the build that names them. Stored chunks are kept 24 hours after last use; an organization holds at most 200 MiB of them and uploads at most 1 GiB a day.","tags":["images"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"digests":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maxItems":10000}},"required":["digests"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"missing":{"type":"array","items":{"type":"string"}}},"required":["missing"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/context/{digest}":{"put":{"operationId":"images.context.put","summary":"Upload one chunk of a build context: at most 1 MiB, named by its SHA-256.","tags":["images"],"parameters":[{"name":"digest","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"sha256":{"type":"string"},"size":{"type":"integer","minimum":0},"stored":{"type":"boolean"}},"required":["sha256","size","stored"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/resolve":{"get":{"operationId":"images.resolve","summary":"The image a reference names: an id, name (its latest tag), name:tag or name@version.","tags":["images"],"parameters":[{"name":"ref","in":"query","required":false,"schema":{"type":"string","maxLength":300,"description":"An image id, a name (its latest tag), name:tag or name@version."},"description":"An image id, a name (its latest tag), name:tag or name@version."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images":{"post":{"operationId":"images.create","summary":"Build a custom image from a Dockerfile, an OCI image or a recipe.","description":"Returns at once with state queued; poll GET /v1/images/{id}, follow GET /v1/images/{id}/logs?follow=true, or send Prefer: wait=N. The build runs in its own Firecracker guest with the same public-web egress as a sandbox, never on the host. An organization runs one build at a time until it holds credit, bought or given, then four. An identical plan in the same organization, last built by the same builder version, is copied instead of rebuilt, and a build that shares its first steps with an earlier one starts from that build's checkpoint. Building is free; the image's storage is recorded as usage.","tags":["images"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"region":{"type":"string","description":"Omit for the default region."},"tags":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$"},"maxItems":16,"description":"Tags this build takes when it is ready. A named image with none given takes latest."},"dockerfile":{"type":"string","maxLength":262144,"description":"A Dockerfile: multi-stage builds, ARG, COPY --from, heredocs, ADD from a URL. FROM a public or private image, FROM scratch, or FROM runtime for Runtime's own base. COPY reads `files` or `context`."},"image":{"type":"string","maxLength":512,"description":"An OCI image to use as it is, plus Runtime's guest agent."},"recipe":{"type":"object","properties":{"base":{"type":"string","description":"runtime (default) or an image reference."},"apt":{"type":"array","items":{"type":"string"},"maxItems":500},"pip":{"type":"array","items":{"type":"string"},"maxItems":500},"npm":{"type":"array","items":{"type":"string"},"maxItems":500},"commands":{"type":"array","items":{"type":"string","maxLength":65536},"maxItems":200},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment every process in the image starts with."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","maxLength":4096,"description":"Path in the build context (Dockerfile) or in the image (recipe)."},"content":{"type":"string","description":"The file's content, UTF-8 text or base64."},"encoding":{"type":"string","enum":["utf8","base64"]},"mode":{"type":"integer","minimum":0,"maximum":511,"description":"Permission bits, 0 to 0777 (decimal 0 to 511)."}},"required":["path","content"],"additionalProperties":false},"maxItems":256},"workdir":{"type":"string","maxLength":4096}},"required":[],"additionalProperties":false,"description":"Packages, commands and files on top of a base, like Modal's and E2B's builders."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","maxLength":4096,"description":"Path in the build context (Dockerfile) or in the image (recipe)."},"content":{"type":"string","description":"The file's content, UTF-8 text or base64."},"encoding":{"type":"string","enum":["utf8","base64"]},"mode":{"type":"integer","minimum":0,"maximum":511,"description":"Permission bits, 0 to 0777 (decimal 0 to 511)."}},"required":["path","content"],"additionalProperties":false},"maxItems":256,"description":"A small build context inline, at most 1 MiB in total. Not with context."},"context":{"type":"object","properties":{"archive":{"type":"object","properties":{"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"size":{"type":"integer","minimum":1,"maximum":104857600},"chunks":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{64}$"},"maxItems":200}},"required":["sha256","size","chunks"],"additionalProperties":false,"description":"The context as a tar archive (gzip allowed), cut into 1 MiB pieces, each uploaded first with PUT /v1/images/context/{digest}."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","maxLength":4096},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"size":{"type":"integer","minimum":0},"mode":{"type":"integer","minimum":0,"maximum":511}},"required":["path","sha256","size"],"additionalProperties":false},"maxItems":20000,"description":"Every regular file in the archive: what COPY resolves against."}},"required":["archive","files"],"additionalProperties":false,"description":"A build context of up to 100 MiB and 20000 files. The SDKs and CLI make it from a folder and its .dockerignore."},"dockerignore":{"type":"string","maxLength":65536,"description":"The context's .dockerignore; excluded files are never copied."},"target":{"type":"string","maxLength":128,"description":"Build this stage as the image instead of the last one."},"buildArgs":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment every process in the image starts with."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment every process in the image starts with."},"start":{"type":["object","null"],"properties":{"command":{"type":"string","maxLength":65536,"description":"A shell command run in the background when a sandbox starts from the image."},"argv":{"type":"array","items":{"type":"string","maxLength":65536},"minItems":1,"maxItems":256},"cwd":{"type":"string","maxLength":4096,"description":"Default: the image's working directory."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":32768},"maxProperties":64,"description":"Environment every process in the image starts with."},"readyCommand":{"type":"string","maxLength":65536,"description":"Create returns once this exits 0 (it is retried). Default when readyPort is absent: none."},"readyPort":{"type":"integer","minimum":1,"maximum":65535,"description":"Create returns once something listens on this port in the sandbox."},"readyTimeoutSeconds":{"type":"integer","minimum":1,"maximum":300,"default":60,"description":"How long create waits for ready before answering with start.state timeout."}},"required":[],"additionalProperties":false,"description":"What a sandbox from this image runs as it starts, and when its create answers. A Dockerfile's CMD, ENTRYPOINT and HEALTHCHECK fill it in; null runs nothing."},"cache":{"type":"boolean","default":true,"description":"Start from, and keep, checkpoints of earlier builds of this organization. false builds every step and pulls the base again. A base named by its tag is pinned to the digest it names now either way, so a moved tag is never served from an old pull."},"build":{"type":"object","properties":{"vcpu":{"type":"integer","minimum":1,"maximum":8,"default":2},"memoryMiB":{"type":"integer","minimum":1024,"maximum":16384,"default":4096},"diskMiB":{"type":"integer","minimum":4096,"maximum":32768,"default":4096,"description":"The build guest's own scratch disk: earlier stages and the context live here. At least 4096 MiB to fit the builder image."},"maxImageMiB":{"type":"integer","minimum":512,"maximum":20480,"default":8192,"description":"The largest the image may be."},"timeoutSeconds":{"type":"integer","minimum":60,"maximum":3600,"default":1800},"cacheMiB":{"type":"integer","minimum":0,"maximum":20480,"description":"The most the layer cache kept by this build may hold. Default: maxImageMiB, at most 8192."}},"required":[],"additionalProperties":false}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"images.list","summary":"List images, newest first. With name, that name's versions.","tags":["images"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["queued","building","ready","failed","deleting"]}},{"name":"name","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/{id}":{"get":{"operationId":"images.get","summary":"An image: its state, version, tags, size, digest, environment, start and build.","tags":["images"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/{id}/logs":{"get":{"operationId":"images.logs","summary":"Build output after a line number. With follow=true (or Accept: application/x-ndjson) the lines stream as they are written.","description":"Streamed: {type: line, seq, at, stream, text} for each line, then {type: done, state, image} when the build has ended, or {type: continue, after} after 110 s, to reconnect with after set.","tags":["images"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":1000000}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"follow","in":"query","required":false,"schema":{"type":"boolean","description":"Stream lines as NDJSON until the build ends."},"description":"Stream lines as NDJSON until the build ends."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer","minimum":0},"at":{"type":"string"},"stream":{"type":"string","enum":["build","system"]},"text":{"type":"string"}},"required":[],"additionalProperties":false}},"nextAfter":{"type":"integer","minimum":0,"description":"Pass as after next time."},"state":{"type":"string"},"truncated":{"type":"boolean"},"done":{"type":"boolean","description":"The build has ended; no more lines will come."}},"required":["lines","nextAfter","done"],"additionalProperties":true}},"application/x-ndjson":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["line","truncated","done","continue","error"]},"seq":{"type":"integer","minimum":0},"text":{"type":"string"},"state":{"type":"string"},"after":{"type":"integer","minimum":0}},"required":["type"],"additionalProperties":true,"description":"One event per line."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/{id}:tag":{"post":{"operationId":"images.tag","summary":"Point a tag of the image's name at this version, moving it from wherever it was.","tags":["images"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$"}},"required":["tag"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/{id}:untag":{"post":{"operationId":"images.untag","summary":"Remove a tag from this version. The version itself stays.","tags":["images"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$"}},"required":["tag"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/images/{id}:delete":{"post":{"operationId":"images.delete","summary":"Delete an image version and its tags. Sandboxes already started from it keep running; a build in progress is cancelled.","tags":["images"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"image"},"status":{"type":"string"},"state":{"type":"string","enum":["queued","building","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"version":{"type":["integer","null"]},"tags":{"type":"array","items":{"type":"string"}},"sizeBytes":{"type":["integer","null"],"description":"The image's whole file, once it is ready. Its storage is charged on this."},"sizeMiB":{"type":["integer","null"]},"storedBytes":{"type":["integer","null"],"description":"The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is."},"error":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","kind","status","state"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volumes":{"post":{"operationId":"volumes.create","summary":"Create a persistent volume, empty or restored from a backup.","description":"Ready in about a second (a restore takes as long as its download); send Prefer: wait=10 to wait for it. Attach it when creating a sandbox with volumes: [{volumeId, path, mode}]. A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it.","tags":["volumes"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"region":{"type":"string","description":"Omit for the default region, or the backup's region."},"sizeMiB":{"type":"integer","minimum":64,"maximum":1048576,"description":"Fixed size, reserved in full. 64 MiB to 1 TiB. Omit when restoring a backup."},"fromBackup":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"A ready backup to restore into the new volume. The new volume is the backup's size, in its region, on whichever host has room, and is ready once the restore is checked."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume"},"status":{"type":"string"},"state":{"type":"string","enum":["creating","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sizeMiB":{"type":"integer"},"usedMiB":{"type":["integer","null"]},"backedUp":{"type":"boolean","description":"A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it."},"backups":{"type":"object","properties":{"daily":{"type":"boolean","description":"Whether a backup is made each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"How long each daily backup is kept."},"lastReadyAt":{"type":["string","null"],"description":"When the newest ready backup was taken."}},"required":[],"additionalProperties":true},"restoredFrom":{"type":["string","null"],"description":"The backup this volume was made from."},"attachments":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"mode":{"type":"string","enum":["rw","snapshot"]},"path":{"type":"string"},"attachedAt":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string"}},"required":["id","kind","status","state","sizeMiB","backedUp"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"volumes.list","summary":"List volumes, newest first.","tags":["volumes"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["creating","ready","failed","deleting"]}},{"name":"name","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume"},"status":{"type":"string"},"state":{"type":"string","enum":["creating","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sizeMiB":{"type":"integer"},"usedMiB":{"type":["integer","null"]},"backedUp":{"type":"boolean","description":"A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it."},"backups":{"type":"object","properties":{"daily":{"type":"boolean","description":"Whether a backup is made each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"How long each daily backup is kept."},"lastReadyAt":{"type":["string","null"],"description":"When the newest ready backup was taken."}},"required":[],"additionalProperties":true},"restoredFrom":{"type":["string","null"],"description":"The backup this volume was made from."},"attachments":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"mode":{"type":"string","enum":["rw","snapshot"]},"path":{"type":"string"},"attachedAt":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string"}},"required":["id","kind","status","state","sizeMiB","backedUp"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volumes/{id}":{"get":{"operationId":"volumes.get","summary":"A volume: its size, what it occupies, its backups and which sandboxes hold it.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume"},"status":{"type":"string"},"state":{"type":"string","enum":["creating","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sizeMiB":{"type":"integer"},"usedMiB":{"type":["integer","null"]},"backedUp":{"type":"boolean","description":"A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it."},"backups":{"type":"object","properties":{"daily":{"type":"boolean","description":"Whether a backup is made each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"How long each daily backup is kept."},"lastReadyAt":{"type":["string","null"],"description":"When the newest ready backup was taken."}},"required":[],"additionalProperties":true},"restoredFrom":{"type":["string","null"],"description":"The backup this volume was made from."},"attachments":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"mode":{"type":"string","enum":["rw","snapshot"]},"path":{"type":"string"},"attachedAt":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string"}},"required":["id","kind","status","state","sizeMiB","backedUp"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volumes/{id}:delete":{"post":{"operationId":"volumes.delete","summary":"Delete a volume and everything on it. Refused while a sandbox holds it. Its backups are kept for their retention.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume"},"status":{"type":"string"},"state":{"type":"string","enum":["creating","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sizeMiB":{"type":"integer"},"usedMiB":{"type":["integer","null"]},"backedUp":{"type":"boolean","description":"A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it."},"backups":{"type":"object","properties":{"daily":{"type":"boolean","description":"Whether a backup is made each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"How long each daily backup is kept."},"lastReadyAt":{"type":["string","null"],"description":"When the newest ready backup was taken."}},"required":[],"additionalProperties":true},"restoredFrom":{"type":["string","null"],"description":"The backup this volume was made from."},"attachments":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"mode":{"type":"string","enum":["rw","snapshot"]},"path":{"type":"string"},"attachedAt":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string"}},"required":["id","kind","status","state","sizeMiB","backedUp"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volumes/{id}:backup":{"post":{"operationId":"volumes.backup","summary":"Back a volume up now, off its host.","description":"The backup is a crash-consistent point in time, taken while sandboxes may be writing. It is ready once copied off the host and checked; send Prefer: wait=60 to wait for it. A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365; the volume's backup retention (7 unless set) when omitted."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume-backup"},"status":{"type":"string"},"state":{"type":"string","enum":["pending","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"volumeId":{"type":"string"},"sizeMiB":{"type":"integer","description":"The volume's size when backed up; a restore is this size."},"trigger":{"type":"string","enum":["manual","daily"]},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"],"description":"What it keeps off the host, compressed and encrypted."},"error":{"type":["string","null"]},"errorCode":{"type":["string","null"],"description":"Why it failed, when a code says it: backup_stalled when its copy off the host never began. Back it up again."},"createdAt":{"type":"string"},"copyStartedAt":{"type":["string","null"],"description":"When its copy off the volume's server began; null while it waits its turn behind other copies there."},"readyAt":{"type":["string","null"]},"expiresAt":{"type":"string"}},"required":["id","kind","status","state","volumeId","sizeMiB","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volumes/{id}:backup-policy":{"post":{"operationId":"volumes.backupPolicy","summary":"Turn daily backups on or off, and set how long each is kept.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"daily":{"type":"boolean","description":"Make a backup each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep each backup; at most seven while the account has no credit."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume"},"status":{"type":"string"},"state":{"type":"string","enum":["creating","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sizeMiB":{"type":"integer"},"usedMiB":{"type":["integer","null"]},"backedUp":{"type":"boolean","description":"A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it."},"backups":{"type":"object","properties":{"daily":{"type":"boolean","description":"Whether a backup is made each day."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"How long each daily backup is kept."},"lastReadyAt":{"type":["string","null"],"description":"When the newest ready backup was taken."}},"required":[],"additionalProperties":true},"restoredFrom":{"type":["string","null"],"description":"The backup this volume was made from."},"attachments":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"mode":{"type":"string","enum":["rw","snapshot"]},"path":{"type":"string"},"attachedAt":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string"}},"required":["id","kind","status","state","sizeMiB","backedUp"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volume-backups":{"get":{"operationId":"volumes.backups.list","summary":"List volume backups, newest first, optionally those of one volume.","tags":["volumes"],"parameters":[{"name":"volumeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","ready","failed","deleting"]}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume-backup"},"status":{"type":"string"},"state":{"type":"string","enum":["pending","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"volumeId":{"type":"string"},"sizeMiB":{"type":"integer","description":"The volume's size when backed up; a restore is this size."},"trigger":{"type":"string","enum":["manual","daily"]},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"],"description":"What it keeps off the host, compressed and encrypted."},"error":{"type":["string","null"]},"errorCode":{"type":["string","null"],"description":"Why it failed, when a code says it: backup_stalled when its copy off the host never began. Back it up again."},"createdAt":{"type":"string"},"copyStartedAt":{"type":["string","null"],"description":"When its copy off the volume's server began; null while it waits its turn behind other copies there."},"readyAt":{"type":["string","null"]},"expiresAt":{"type":"string"}},"required":["id","kind","status","state","volumeId","sizeMiB","expiresAt"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volume-backups/{id}":{"get":{"operationId":"volumes.backups.get","summary":"A volume backup: its state, size, what it stores and when it expires.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume-backup"},"status":{"type":"string"},"state":{"type":"string","enum":["pending","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"volumeId":{"type":"string"},"sizeMiB":{"type":"integer","description":"The volume's size when backed up; a restore is this size."},"trigger":{"type":"string","enum":["manual","daily"]},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"],"description":"What it keeps off the host, compressed and encrypted."},"error":{"type":["string","null"]},"errorCode":{"type":["string","null"],"description":"Why it failed, when a code says it: backup_stalled when its copy off the host never began. Back it up again."},"createdAt":{"type":"string"},"copyStartedAt":{"type":["string","null"],"description":"When its copy off the volume's server began; null while it waits its turn behind other copies there."},"readyAt":{"type":["string","null"]},"expiresAt":{"type":"string"}},"required":["id","kind","status","state","volumeId","sizeMiB","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/volume-backups/{id}:delete":{"post":{"operationId":"volumes.backups.delete","summary":"Delete a volume backup and its copy off the host.","tags":["volumes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"volume-backup"},"status":{"type":"string"},"state":{"type":"string","enum":["pending","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"volumeId":{"type":"string"},"sizeMiB":{"type":"integer","description":"The volume's size when backed up; a restore is this size."},"trigger":{"type":"string","enum":["manual","daily"]},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"],"description":"What it keeps off the host, compressed and encrypted."},"error":{"type":["string","null"]},"errorCode":{"type":["string","null"],"description":"Why it failed, when a code says it: backup_stalled when its copy off the host never began. Back it up again."},"createdAt":{"type":"string"},"copyStartedAt":{"type":["string","null"],"description":"When its copy off the volume's server began; null while it waits its turn behind other copies there."},"readyAt":{"type":["string","null"]},"expiresAt":{"type":"string"}},"required":["id","kind","status","state","volumeId","sizeMiB","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}:snapshot":{"post":{"operationId":"snapshots.create","summary":"Snapshot a running or paused sandbox, to start new sandboxes from.","description":"A running sandbox is paused for the moment it takes to capture, then woken again, as a fork's source is; the answer comes once the capture is over (up to a minute; one still capturing then leaves the sandbox paused until it is ready, so wake it after). A paused one stays paused; send Prefer: wait=10 to wait for its snapshot to be ready. Start copies with POST /v1/sandboxes and snapshot: <id>. Memory snapshots (the default) continue the saved machine: same files, same running processes, same memory, its own clock and a freshly seeded random number generator. A process that seeded its own generator before the snapshot keeps that seed in every copy. With mode: disk, only files are saved and each copy boots afresh without the old processes. A snapshot keeps the saved state used to start new sandboxes. Retained snapshots are copied off the host after any pending memory compression finishes, encrypted under your organization's own key; backedUp is true once that copy is checked. If the host is lost, the snapshot is restored onto another host from that copy and forks run there (they answer snapshot_restoring meanwhile). Only the root disk is kept, so a sandbox with volumes cannot be snapshotted.","tags":["snapshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365, never past a year from when it was taken. Omit it to keep the snapshot while your account has credit, up to a year from when it was taken (seven days without credit)."},"mode":{"type":"string","enum":["memory","disk"],"description":"memory (default) saves the whole machine; disk saves files for a fresh boot, without old processes."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/snapshots":{"get":{"operationId":"snapshots.list","summary":"List snapshots, newest first.","tags":["snapshots"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["capturing","ready","failed","deleting"]}},{"name":"name","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},{"name":"sandboxId","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/snapshots/{id}":{"get":{"operationId":"snapshots.get","summary":"A snapshot: its state, the machine it starts, what it stores and when it expires.","tags":["snapshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/snapshots/{id}:update":{"post":{"operationId":"snapshots.update","summary":"Change a snapshot's name or replace its labels.","description":"Omitted fields stay unchanged. An empty labels object clears labels; a null name clears the name. Captured bytes, retention and billing are unchanged.","tags":["snapshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"ifLabels":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"maxProperties":32,"description":"Only update if the current complete labels equal these; otherwise snapshot_metadata_changed. Omit for an unconditional update."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/snapshots/{id}:extend":{"post":{"operationId":"snapshots.extend","summary":"Keep a snapshot for retentionDays from now, or while your account has credit.","tags":["snapshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"retentionDays":{"type":["integer","null"],"minimum":1,"maximum":365,"description":"Days to keep it from now, 1 to 365, never past a year from when it was taken; null keeps it while your account has credit, up to a year from when it was taken."}},"required":["retentionDays"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/snapshots/{id}:delete":{"post":{"operationId":"snapshots.delete","summary":"Delete a snapshot. Sandboxes already started from it keep running.","tags":["snapshots"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","const":"snapshot"},"mode":{"type":"string","enum":["memory","disk"]},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"placement":{"type":["string","null"],"description":"Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create."},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":["integer","null"],"description":"Days it is kept, or null: kept while your account has credit, up to a year from when it was taken."},"compressionPending":{"type":"boolean","description":"True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression."},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true."},"backedUp":{"type":"boolean","description":"Whether its copy off the host is made and checked."},"durability":{"type":"object","properties":{"state":{"type":"string","enum":["none","pending","durable","failed","restoring"],"description":"none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied."},"durableAt":{"type":["string","null"]},"storedBytes":{"type":["integer","null"],"description":"What the copy off the host stores, compressed and encrypted."}},"required":[],"additionalProperties":true},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"readyAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"description":"When it is deleted. Null while it is kept as long as your account has credit."}},"required":["id","kind","status","state","sourceSandboxId","shape","expiresAt"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/mounts":{"post":{"operationId":"sandboxes.mounts.create","summary":"Mount an S3, R2 or Google Cloud Storage bucket at a path in a running sandbox.","description":"The sandbox never holds the bucket's key: its mount client signs with a placeholder, and the egress proxy signs every request again with the key in your secret. The first mount in a sandbox installs rclone and fuse3, which takes a few seconds more. A mount lasts through a pause and a wake, and ends when the sandbox stops.","tags":["mounts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["s3","r2","gcs"],"description":"s3 for Amazon S3 (or any S3-compatible store with endpoint), r2 for Cloudflare R2, gcs for Google Cloud Storage through its S3-compatible XML API with HMAC keys."},"bucket":{"type":"string","description":"The bucket's name."},"path":{"type":"string","description":"Where it appears in the sandbox, such as /data."},"prefix":{"type":"string","description":"Mount only the keys under this prefix."},"region":{"type":"string","description":"The bucket's region; us-east-1 for S3 when omitted."},"endpoint":{"type":"string","description":"An https:// URL for any other S3-compatible store (MinIO, Backblaze B2...)."},"accountId":{"type":"string","description":"For r2: your Cloudflare account id."},"secret":{"type":"string","description":"The name of the secret holding ACCESS_KEY_ID:SECRET_KEY, stored with header Authorization and format \"AWS4-HMAC-SHA256 {value}\" for the endpoint's host. The sandbox never sees the key: the egress proxy signs each request. Omit for a public bucket."},"readOnly":{"type":"boolean","description":"Mount it read-only."}},"required":["provider","bucket","path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"provider":{"type":"string"},"bucket":{"type":"string"},"prefix":{"type":["string","null"]},"endpoint":{"type":"string"},"secret":{"type":["string","null"]},"readOnly":{"type":"boolean"},"mounted":{"type":"boolean"}},"required":["path","bucket","mounted"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"sandboxes.mounts.list","summary":"The buckets mounted in a sandbox, and whether each is mounted now.","tags":["mounts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"provider":{"type":"string"},"bucket":{"type":"string"},"prefix":{"type":["string","null"]},"endpoint":{"type":"string"},"secret":{"type":["string","null"]},"readOnly":{"type":"boolean"},"mounted":{"type":"boolean"}},"required":["path","bucket","mounted"],"additionalProperties":true}}},"required":["data"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/mounts:unmount":{"post":{"operationId":"sandboxes.mounts.delete","summary":"Unmount a bucket. Files already written to it stay in the bucket.","tags":["mounts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"mounted":{"type":"boolean"}},"required":["path","mounted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/tailscale":{"post":{"operationId":"sandboxes.tailscale.up","summary":"Join a paid sandbox to your Tailscale network with your auth key.","description":"The auth key is read from your job secret and given to the sandbox's tailscaled in memory; it is never answered, logged or written to the sandbox's disk. The machine is ephemeral: logging out takes it off the tailnet at once, and after a stop or a delete Tailscale removes it once it has been offline a while. The first join in a sandbox downloads Tailscale, which takes a few seconds more. While it is on a tailnet a sandbox is not forked or snapshotted from memory.","tags":["tailscale"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"authKeySecret":{"type":"string","description":"The name of a job secret holding a Tailscale auth key (runtime secrets set NAME --jobs). Use an ephemeral, tagged key; a reusable one lets the sandbox log in again by itself after a long pause.","examples":["TS_AUTHKEY"]},"hostname":{"type":"string","description":"The machine's name on the tailnet, a DNS label. Default: the sandbox's name, or runtime- and its id's first eight characters."},"tags":{"type":"array","items":{"type":"string","examples":["tag:ci"]},"maxItems":16,"description":"Tailscale tags to advertise; the key must be allowed them."}},"required":["authKeySecret"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"running":{"type":"boolean"},"state":{"type":["string","null"]},"mode":{"type":["string","null"]},"hostname":{"type":["string","null"]},"dnsName":{"type":["string","null"]},"addresses":{"type":"array","items":{"type":"string"}},"proxy":{"type":["string","null"]}},"required":["running","addresses"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"sandboxes.tailscale.get","summary":"Whether a sandbox is on a tailnet, and its addresses there.","tags":["tailscale"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"running":{"type":"boolean"},"state":{"type":["string","null"]},"mode":{"type":["string","null"]},"hostname":{"type":["string","null"]},"dnsName":{"type":["string","null"]},"addresses":{"type":"array","items":{"type":"string"}},"proxy":{"type":["string","null"]}},"required":["running","addresses"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"sandboxes.tailscale.down","summary":"Take a sandbox off its tailnet. The machine is removed from the tailnet at once.","tags":["tailscale"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"left":{"type":"boolean"}},"required":["left"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/previews":{"post":{"operationId":"previews.create","summary":"Share a port of a sandbox at a public HTTPS address.","description":"Creates the preview for this port, or changes its visibility and embedOrigins if it exists (so a retry is harmless). Returns the URL and, for a private preview, a signed token. WebSockets are supported. The server must listen on 0.0.0.0 or localhost inside the sandbox. embedOrigins limits which sites may show it in an iframe.","tags":["previews"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port inside the sandbox."},"visibility":{"type":"string","enum":["private","public"],"description":"private (default): a token is needed. public: anyone with the address; only for an account with a kept top-up."},"ttlSeconds":{"type":"integer","minimum":60,"maximum":604800,"default":86400,"description":"The token's lifetime in seconds."},"expiresAt":{"type":"string","format":"date-time","description":"An absolute private-token deadline, at least a minute and at most a week ahead. The token never outlives it."},"embedOrigins":{"type":["array","null"],"maxItems":16,"items":{"type":"string","minLength":1,"maxLength":300},"description":"The sites that may show this preview in an iframe, as origins: https://app.example.com, https://*.example.com for its subdomains, or http://localhost:3000. Up to 16. Any other site's iframe is refused, and a private link's token works in an iframe only on these. Omitted on a preview that exists: kept as it is. [] or null: any site (the default)."}},"required":["port"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer"},"visibility":{"type":"string"},"url":{"type":"string","description":"The address. A private preview also needs the token."},"token":{"type":["string","null"],"description":"Private previews: a token signed for this answer. Every create and read signs its own, each with its own tokenExpiresAt (a day unless ttlSeconds or expiresAt asks otherwise); tokens signed before keep working until their own expiry or a rotate. Null for a key that cannot run commands in the sandbox, such as a read-only key."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time","description":"When this answer's token stops working. It is not stored on the preview: another read signs another token with its own expiry, and does not shorten or extend this one."},"urlWithToken":{"type":["string","null"],"description":"Private previews: a link that carries the token once, for a browser."},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"embedOrigins":{"type":["array","null"],"items":{"type":"string"},"description":"The sites that may show it in an iframe; null for any site."},"createdAt":{"type":"string","format":"date-time"},"hint":{"type":"string","description":"How to share it, in one line."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"previews.list","summary":"Every preview of a sandbox, lowest port first, each private one with a fresh token that lasts a day; tokens signed before keep their own expiry.","tags":["previews"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer"},"visibility":{"type":"string"},"url":{"type":"string","description":"The address. A private preview also needs the token."},"token":{"type":["string","null"],"description":"Private previews: a token signed for this answer. Every create and read signs its own, each with its own tokenExpiresAt (a day unless ttlSeconds or expiresAt asks otherwise); tokens signed before keep working until their own expiry or a rotate. Null for a key that cannot run commands in the sandbox, such as a read-only key."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time","description":"When this answer's token stops working. It is not stored on the preview: another read signs another token with its own expiry, and does not shorten or extend this one."},"urlWithToken":{"type":["string","null"],"description":"Private previews: a link that carries the token once, for a browser."},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"embedOrigins":{"type":["array","null"],"items":{"type":"string"},"description":"The sites that may show it in an iframe; null for any site."},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/previews/{port}":{"get":{"operationId":"previews.get","summary":"One preview, with a fresh token if it is private.","tags":["previews"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"port","in":"path","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,4}$","description":"The previewed port."}},{"name":"ttlSeconds","in":"query","required":false,"schema":{"type":"integer","minimum":60,"maximum":604800,"default":86400,"description":"The token's lifetime in seconds."},"description":"The token's lifetime in seconds."},{"name":"expiresAt","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"An absolute private-token deadline, at least a minute and at most a week ahead. The token never outlives it."},"description":"An absolute private-token deadline, at least a minute and at most a week ahead. The token never outlives it."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer"},"visibility":{"type":"string"},"url":{"type":"string","description":"The address. A private preview also needs the token."},"token":{"type":["string","null"],"description":"Private previews: a token signed for this answer. Every create and read signs its own, each with its own tokenExpiresAt (a day unless ttlSeconds or expiresAt asks otherwise); tokens signed before keep working until their own expiry or a rotate. Null for a key that cannot run commands in the sandbox, such as a read-only key."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time","description":"When this answer's token stops working. It is not stored on the preview: another read signs another token with its own expiry, and does not shorten or extend this one."},"urlWithToken":{"type":["string","null"],"description":"Private previews: a link that carries the token once, for a browser."},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"embedOrigins":{"type":["array","null"],"items":{"type":"string"},"description":"The sites that may show it in an iframe; null for any site."},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"previews.delete","summary":"Stop sharing this port. Its open connections are closed before this answers.","tags":["previews"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"port","in":"path","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,4}$","description":"The previewed port."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer"},"deleted":{"type":"boolean","const":true}},"required":["id","sandboxId","port","deleted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/previews/{port}:rotate":{"post":{"operationId":"previews.rotate","summary":"Refuse every token issued for this preview so far, and return a new one.","tags":["previews"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"port","in":"path","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,4}$","description":"The previewed port."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer"},"visibility":{"type":"string"},"url":{"type":"string","description":"The address. A private preview also needs the token."},"token":{"type":["string","null"],"description":"Private previews: a token signed for this answer. Every create and read signs its own, each with its own tokenExpiresAt (a day unless ttlSeconds or expiresAt asks otherwise); tokens signed before keep working until their own expiry or a rotate. Null for a key that cannot run commands in the sandbox, such as a read-only key."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time","description":"When this answer's token stops working. It is not stored on the preview: another read signs another token with its own expiry, and does not shorten or extend this one."},"urlWithToken":{"type":["string","null"],"description":"Private previews: a link that carries the token once, for a browser."},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"embedOrigins":{"type":["array","null"],"items":{"type":"string"},"description":"The sites that may show it in an iframe; null for any site."},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/network":{"get":{"operationId":"network.get","summary":"A sandbox's network rules, whether its host enforces them, and whether host:port reach is open to this organization.","tags":["network"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxId":{"type":"string"},"internet":{"type":"boolean"},"allow":{"type":"array","items":{"type":"string"}},"deny":{"type":"array","items":{"type":"string"}},"connect":{"type":"array","items":{"type":"string"}},"version":{"type":"integer","minimum":0},"enforced":{"type":"boolean","description":"The sandbox's host confirmed it holds these rules (version)."},"enforcedVersion":{"type":"integer","minimum":0},"ports":{"type":"array","items":{"type":"integer"},"description":"Ports reachable without a connect entry."},"openPorts":{"type":"boolean","description":"Every public host:port is reachable, except forbiddenPorts: a paid sandbox of an organization with a paid purchase."},"connectAllowed":{"type":"boolean","description":"This organization may use connect."},"connectReason":{"type":"string","description":"paid, granted, not_paid, revoked, suspended, or trial (a sandbox without credit reaches ports 80 and 443 only)."},"forbiddenPorts":{"type":"array","items":{"type":"integer"},"description":"Never reachable, with or without connect."},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"network.set","summary":"Replace a sandbox's network rules: internet on or off, allowed and denied destinations, host:port pairs.","description":"Takes effect on open connections too: a connection the new rules refuse is cut. Private addresses are always refused. A paid sandbox of an organization with a paid purchase reaches every port, narrowed by allow and deny; a sandbox without credit reaches ports 80 and 443. Some ports (telnet, SMB, IRC, and mail unless enabled by support) are never reachable.","tags":["network"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"internet":{"type":"boolean","description":"false refuses every outbound connection."},"allow":{"type":"array","items":{"type":"string","maxLength":255,"description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range.","examples":["registry.npmjs.org","*.github.com","140.82.112.0/20"]},"maxItems":256,"description":"When not empty, only these destinations are reachable, on every port the sandbox may use."},"deny":{"type":"array","items":{"type":"string","maxLength":255,"description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range.","examples":["registry.npmjs.org","*.github.com","140.82.112.0/20"]},"maxItems":256,"description":"Never reachable. Wins over everything."},"connect":{"type":"array","items":{"type":"string","maxLength":262,"description":"host:port beyond the web ports, reached as a TCP tunnel through the sandbox's proxy: your own database, a git host over ssh.","examples":["db.example.com:5432","github.com:22","203.0.113.7:6379"]},"maxItems":64,"description":"host:port pairs beyond ports 80 and 443. A paid sandbox of an organization with a paid purchase reaches every port already; list pairs here when you narrow it with allow. Sandboxes without credit stay on ports 80 and 443."}},"required":["internet"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxId":{"type":"string"},"internet":{"type":"boolean"},"allow":{"type":"array","items":{"type":"string"}},"deny":{"type":"array","items":{"type":"string"}},"connect":{"type":"array","items":{"type":"string"}},"version":{"type":"integer","minimum":0},"enforced":{"type":"boolean","description":"The sandbox's host confirmed it holds these rules (version)."},"enforcedVersion":{"type":"integer","minimum":0},"ports":{"type":"array","items":{"type":"integer"},"description":"Ports reachable without a connect entry."},"openPorts":{"type":"boolean","description":"Every public host:port is reachable, except forbiddenPorts: a paid sandbox of an organization with a paid purchase."},"connectAllowed":{"type":"boolean","description":"This organization may use connect."},"connectReason":{"type":"string","description":"paid, granted, not_paid, revoked, suspended, or trial (a sandbox without credit reaches ports 80 and 443 only)."},"forbiddenPorts":{"type":"array","items":{"type":"integer"},"description":"Never reachable, with or without connect."},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/domains":{"post":{"operationId":"domains.add","summary":"Serve a sandbox's port or an App at your own hostname, with automatic HTTPS.","description":"Claims the hostname and answers the DNS records to set: a TXT record that proves the name is yours, and a CNAME (an A record for an apex name) that sends visitors here. Checks the TXT record at once. Needs a kept top-up. Calling it again with another sandbox or port points the name there. With appId instead of sandboxId and port, an App serves the name through every deploy and rollback; add its _acme-challenge CNAME too, and point the name at the App once certificate.ready is true.","tags":["domains"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"type":"string","maxLength":253},"sandboxId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"The sandbox to serve, with port."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."},"appId":{"type":"string","description":"The App or Function to serve, instead of a sandbox."}},"required":["hostname"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"sandboxId":{"type":["string","null"],"description":"The sandbox it serves; null for an App's."},"appId":{"type":["string","null"],"description":"The App it serves; null for a sandbox's port."},"port":{"type":"integer"},"state":{"type":"string","description":"pending (prove it with the TXT record), active, or released."},"url":{"type":"string"},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}},"required":[],"additionalProperties":false}},"verifiedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"},"checkError":{"type":["string","null"]},"certificate":{"type":["object","null"],"description":"An App's domain's certificate, issued before visitors arrive: point the name at the App once ready is true. Null for a sandbox's.","properties":{"ready":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"issuers":{"type":"array","items":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"pointed":{"type":["boolean","null"],"description":"The name resolves to Runtime's edge now."},"hint":{"type":"string"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"domains.list","summary":"Your custom domains, pending and active.","tags":["domains"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"sandboxId":{"type":["string","null"],"description":"The sandbox it serves; null for an App's."},"appId":{"type":["string","null"],"description":"The App it serves; null for a sandbox's port."},"port":{"type":"integer"},"state":{"type":"string","description":"pending (prove it with the TXT record), active, or released."},"url":{"type":"string"},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}},"required":[],"additionalProperties":false}},"verifiedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"},"checkError":{"type":["string","null"]},"certificate":{"type":["object","null"],"description":"An App's domain's certificate, issued before visitors arrive: point the name at the App once ready is true. Null for a sandbox's.","properties":{"ready":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"issuers":{"type":"array","items":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/domains/{hostname}":{"get":{"operationId":"domains.get","summary":"One custom domain and the DNS records it needs.","tags":["domains"],"parameters":[{"name":"hostname","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{4,253}$","description":"The hostname, such as app.example.com."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"sandboxId":{"type":["string","null"],"description":"The sandbox it serves; null for an App's."},"appId":{"type":["string","null"],"description":"The App it serves; null for a sandbox's port."},"port":{"type":"integer"},"state":{"type":"string","description":"pending (prove it with the TXT record), active, or released."},"url":{"type":"string"},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}},"required":[],"additionalProperties":false}},"verifiedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"},"checkError":{"type":["string","null"]},"certificate":{"type":["object","null"],"description":"An App's domain's certificate, issued before visitors arrive: point the name at the App once ready is true. Null for a sandbox's.","properties":{"ready":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"issuers":{"type":"array","items":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"domains.remove","summary":"Stop serving the hostname, open connections included, before this answers. Remove its DNS records too.","tags":["domains"],"parameters":[{"name":"hostname","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{4,253}$","description":"The hostname, such as app.example.com."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/domains/{hostname}:verify":{"post":{"operationId":"domains.verify","summary":"Check the TXT record now, and whether the name points here.","tags":["domains"],"parameters":[{"name":"hostname","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9.-]{4,253}$","description":"The hostname, such as app.example.com."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"sandboxId":{"type":["string","null"],"description":"The sandbox it serves; null for an App's."},"appId":{"type":["string","null"],"description":"The App it serves; null for a sandbox's port."},"port":{"type":"integer"},"state":{"type":"string","description":"pending (prove it with the TXT record), active, or released."},"url":{"type":"string"},"disabled":{"type":"boolean","description":"Turned off by Runtime after a report. Contact support."},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}},"required":[],"additionalProperties":false}},"verifiedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"},"checkError":{"type":["string","null"]},"certificate":{"type":["object","null"],"description":"An App's domain's certificate, issued before visitors arrive: point the name at the App once ready is true. Null for a sandbox's.","properties":{"ready":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time"},"issuers":{"type":"array","items":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"},"pointed":{"type":["boolean","null"],"description":"The name resolves to Runtime's edge now."},"hint":{"type":"string"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/ports":{"post":{"operationId":"ports.open","summary":"Open a public TCP port to a port of a sandbox: a database, a game server, anything that is not HTTP.","description":"Returns address:publicPort. Raw TCP, carried as it is; use your service's own authentication and TLS. Needs a kept top-up; at most 5 per sandbox and 20 per organization. Calling it again for the same sandbox and port returns the same public port.","tags":["ports"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"The sandbox that serves it."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."}},"required":["sandboxId","port"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer","minimum":{"description":"The port inside the sandbox."}},"address":{"type":"string","description":"The public address to connect to."},"publicPort":{"type":"integer"},"connect":{"type":"string","description":"address:publicPort, for a client's host and port."},"protocol":{"type":"string","description":"tcp. UDP is not carried."},"disabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"hint":{"type":"string"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"ports.list","summary":"Your open TCP ports, or one sandbox's.","tags":["ports"],"parameters":[{"name":"sandboxId","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sandboxId":{"type":"string"},"port":{"type":"integer","minimum":{"description":"The port inside the sandbox."}},"address":{"type":"string","description":"The public address to connect to."},"publicPort":{"type":"integer"},"connect":{"type":"string","description":"address:publicPort, for a client's host and port."},"protocol":{"type":"string","description":"tcp. UDP is not carried."},"disabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/ports/{id}":{"delete":{"operationId":"ports.close","summary":"Close a TCP port. Its open connections are closed before this answers.","tags":["ports"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/ips":{"post":{"operationId":"ips.reserve","summary":"Reserve a dedicated outbound address: every sandbox of your organization sends from it.","description":"For allow-lists at your database, API provider or firewall. One per address family; calling it again returns the one you have. No other organization sends from it while you hold it, or for 30 days after you release it. Needs credit on the account.","tags":["ips"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"family":{"type":"integer","minimum":4,"maximum":6,"description":"4 (default) or 6."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"address":{"type":"string","description":"Every sandbox of the organization sends from it while funded."},"family":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"ips.list","summary":"Your dedicated outbound addresses.","tags":["ips"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"address":{"type":"string","description":"Every sandbox of the organization sends from it while funded."},"family":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/ips/{id}":{"delete":{"operationId":"ips.release","summary":"Release a dedicated address. Sandboxes go back to the shared addresses at once.","tags":["ips"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/wireguard":{"get":{"operationId":"networks.wireguard.get","summary":"Your private network: its WireGuard endpoint, peers, and each sandbox's address in it.","tags":["networks"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"subnet":{"type":"string"},"gatewayAddress":{"type":"string"},"endpoint":{"type":"string","description":"Where peers send WireGuard: address:udpPort."},"gatewayPublicKey":{"type":["string","null"],"description":"Null until a funded gateway is ready."},"disabled":{"type":"boolean"},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string","description":"Reach this sandbox's ports at this address."},"state":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"networks.wireguard.create","summary":"Create your private network: a WireGuard tunnel from your own network into your sandboxes.","description":"One per organization. Every sandbox gets an address in the subnet (default 10.250.0.0/16; choose one your network does not use). Then add a peer for each of your machines or routers. Needs a kept top-up. Calling it again returns the network you have.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subnet":{"type":"string","maxLength":18,"description":"A private IPv4 range from /16 to /24. Default 10.250.0.0/16."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"subnet":{"type":"string"},"gatewayAddress":{"type":"string"},"endpoint":{"type":"string","description":"Where peers send WireGuard: address:udpPort."},"gatewayPublicKey":{"type":["string","null"],"description":"Null until a funded gateway is ready."},"disabled":{"type":"boolean"},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string","description":"Reach this sandbox's ports at this address."},"state":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"networks.wireguard.delete","summary":"Delete your private network and every peer. Tunnels close within seconds.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/wireguard/peers":{"post":{"operationId":"networks.wireguard.peers.add","summary":"Add one of your machines or routers to the private network, and get its wg-quick file.","description":"Send your peer's public key, or leave it out and Runtime generates the pair and puts the private key in config once. routes are your own ranges behind the peer that sandboxes may reach. At most 16 peers.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"publicKey":{"type":"string","pattern":"^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$","description":"The peer's WireGuard public key. Leave it out and Runtime generates the pair."},"routes":{"type":"array","items":{"type":"string","maxLength":18},"maxItems":16,"description":"Private IPv4 ranges on your side of this peer that sandboxes may reach, such as 10.0.0.0/16."}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"tunnel":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"subnet":{"type":"string"},"gatewayAddress":{"type":"string"},"endpoint":{"type":"string","description":"Where peers send WireGuard: address:udpPort."},"gatewayPublicKey":{"type":["string","null"],"description":"Null until a funded gateway is ready."},"disabled":{"type":"boolean"},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string","description":"Reach this sandbox's ports at this address."},"state":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false},"peer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false},"config":{"type":["string","null"],"description":"A wg-quick file or a draft when configReady is false. Keep it: a Runtime-generated private key is delivered here once. Complete the gateway PublicKey before using a draft."},"configReady":{"type":"boolean","description":"Whether config includes the gateway public key. Funding and access are reported separately on tunnel."},"hint":{"type":"string"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/wireguard/peers/{id}:rotate":{"post":{"operationId":"networks.wireguard.peers.rotate","summary":"Give a peer a new key. The old key stops working within seconds.","tags":["networks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"publicKey":{"type":"string","pattern":"^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$","description":"The peer's WireGuard public key. Leave it out and Runtime generates the pair."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"tunnel":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"subnet":{"type":"string"},"gatewayAddress":{"type":"string"},"endpoint":{"type":"string","description":"Where peers send WireGuard: address:udpPort."},"gatewayPublicKey":{"type":["string","null"],"description":"Null until a funded gateway is ready."},"disabled":{"type":"boolean"},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string","description":"Reach this sandbox's ports at this address."},"state":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false},"peer":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false},"config":{"type":["string","null"],"description":"A wg-quick file or a draft when configReady is false. Keep it: a Runtime-generated private key is delivered here once. Complete the gateway PublicKey before using a draft."},"configReady":{"type":"boolean","description":"Whether config includes the gateway public key. Funding and access are reported separately on tunnel."},"hint":{"type":"string"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/wireguard/peers/{id}":{"delete":{"operationId":"networks.wireguard.peers.remove","summary":"Remove a peer. Its tunnel and connections end within seconds.","tags":["networks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"funded":{"type":"boolean","description":"Funding permits traffic. False disables traffic while retaining the reservation; check balance, spending limits and account permissions."},"fundedUntil":{"type":["string","null"],"format":"date-time","description":"Last funded-through timestamp, possibly in the past. Null means no meter exists. Free IPv6 also receives renewable deadlines."},"rateMicros":{"type":"integer","minimum":0,"description":"Immutable quoted monthly price in millionths of a US dollar."},"rateUnit":{"type":"string","enum":["unit_month"]},"id":{"type":"string"},"subnet":{"type":"string"},"gatewayAddress":{"type":"string"},"endpoint":{"type":"string","description":"Where peers send WireGuard: address:udpPort."},"gatewayPublicKey":{"type":["string","null"],"description":"Null until a funded gateway is ready."},"disabled":{"type":"boolean"},"peers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"},"address":{"type":"string","description":"The peer's address inside the private network."},"routes":{"type":"array","items":{"type":"string"},"description":"Your own ranges behind this peer, which sandboxes may reach through it."},"createdAt":{"type":"string","format":"date-time"},"rotatedAt":{"type":["string","null"],"format":"date-time"}},"required":[],"additionalProperties":false}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string","description":"Reach this sandbox's ports at this address."},"state":{"type":"string"}},"required":[],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/private":{"get":{"operationId":"networks.private.get","summary":"Whether your sandboxes reach each other by name.","tags":["networks"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether your sandboxes reach each other by name now."},"suffix":{"type":"string","const":"sandbox.internal","description":"Reach a sandbox at <name>.sandbox.internal or <id>.sandbox.internal."},"allowed":{"type":"boolean","description":"Whether this account may turn it on: it must have a kept top-up."},"why":{"type":["string","null"],"description":"Why it may not, when allowed is false: not_paid, revoked or suspended."},"enabledAt":{"type":["string","null"],"description":"When it was last turned on."},"disabledAt":{"type":["string","null"],"description":"When it was last turned off."}},"required":["enabled","suffix","allowed","why","enabledAt","disabledAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"networks.private.set","summary":"Let your sandboxes reach each other by name, or stop them.","description":"Needs a kept top-up, and free. When on, a program in any of your sandboxes connects to another of your sandboxes at <name>.sandbox.internal:<port> (the name it was created with) or <id>.sandbox.internal:<port>, over TCP, on any port but 10800, 10802 and 10853, which Runtime uses inside every sandbox. A paused sandbox wakes when a connection reaches it. Only your organization's sandboxes answer; nothing else, inside Runtime or out, can reach them this way. Off by default. Turning it off cuts open connections between your sandboxes within seconds.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true: your sandboxes reach each other by name. false: they stop, and open connections between them are cut within seconds."}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether your sandboxes reach each other by name now."},"suffix":{"type":"string","const":"sandbox.internal","description":"Reach a sandbox at <name>.sandbox.internal or <id>.sandbox.internal."},"allowed":{"type":"boolean","description":"Whether this account may turn it on: it must have a kept top-up."},"why":{"type":["string","null"],"description":"Why it may not, when allowed is false: not_paid, revoked or suspended."},"enabledAt":{"type":["string","null"],"description":"When it was last turned on."},"disabledAt":{"type":["string","null"],"description":"When it was last turned off."}},"required":["enabled","suffix","allowed","why","enabledAt","disabledAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/signed-requests":{"get":{"operationId":"networks.signedRequests.get","summary":"Whether your sandboxes' requests carry Runtime's signature.","tags":["networks"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether your sandboxes may get Runtime's request signature now."},"allowed":{"type":"boolean","description":"Whether this account may turn it on: it must have credit."},"why":{"type":["string","null"],"description":"Why it may not, when allowed is false: no_credit, revoked or suspended."},"enabledAt":{"type":["string","null"],"description":"When it was last turned on."},"disabledAt":{"type":["string","null"],"description":"When it was last turned off."}},"required":["enabled","allowed","why","enabledAt","disabledAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"networks.signedRequests.set","summary":"Let your sandboxes sign their requests as Runtime's agents, or stop them.","description":"Needs credit on the account, and free. When on, a sandbox can get Runtime's Web Bot Auth signature (IETF draft, RFC 9421 HTTP message signatures) for its outbound HTTP requests, so sites behind Cloudflare and other bot managers recognise them as Runtime's agents. A program gets the headers from https://withruntime.com/api/signed-requests/sign (documented at /docs/egress). Off by default. Turning it off stops new signatures at once; ones already given expire within 5 minutes.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true: your sandboxes may get Runtime's request signature. false: new signatures stop at once, and ones already given expire within 5 minutes."}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether your sandboxes may get Runtime's request signature now."},"allowed":{"type":"boolean","description":"Whether this account may turn it on: it must have credit."},"why":{"type":["string","null"],"description":"Why it may not, when allowed is false: no_credit, revoked or suspended."},"enabledAt":{"type":["string","null"],"description":"When it was last turned on."},"disabledAt":{"type":["string","null"],"description":"When it was last turned off."}},"required":["enabled","allowed","why","enabledAt","disabledAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop:start":{"post":{"operationId":"desktop.start","summary":"Start the sandbox's desktop and share a live view of it.","description":"Starts Xvfb, a window manager, VNC on the sandbox's loopback and noVNC on port 6080, and returns streamUrl: a private preview link that opens the live desktop in a browser. Idempotent.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"width":{"type":"integer","minimum":320,"maximum":3840},"height":{"type":"integer","minimum":240,"maximum":2160}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"display":{"type":"string"},"size":{"type":"string","description":"WIDTHxHEIGHT."},"streamUrl":{"type":"string","description":"Opens the live desktop in a browser; carries a private preview token."},"preview":{"type":"object"}},"required":["ok","streamUrl"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop:stop":{"post":{"operationId":"desktop.stop","summary":"Stop the sandbox's desktop.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop/screenshot":{"get":{"operationId":"desktop.screenshot","summary":"A screenshot of the desktop, as image/png (or image/jpeg with format=jpeg).","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["png","jpeg"]}},{"name":"quality","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","contentMediaType":"image/png"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop:act":{"post":{"operationId":"desktop.act","summary":"One mouse, keyboard or window action on the desktop.","description":"move {x,y}; click {x?,y?,button?,double?}; mouseDown/mouseUp {button?}; drag {from,to}; scroll {dy,dx?,x?,y?}; type {text}; key {keys}; cursor; windows; focus {windowId}; open {url}; launch {argv}; status.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["move","click","mouseDown","mouseUp","drag","scroll","type","key","cursor","windows","focus","open","launch","status"],"description":"What to do. See each field for which actions use it."},"x":{"type":"integer","minimum":0,"maximum":16384},"y":{"type":"integer","minimum":0,"maximum":16384},"button":{"type":"string","enum":["left","middle","right"]},"double":{"type":"boolean","description":"click: a double click."},"from":{"type":"array","items":{"type":"integer","minimum":0,"maximum":16384},"minItems":2,"maxItems":2,"description":"drag: [x, y] to press at."},"to":{"type":"array","items":{"type":"integer","minimum":0,"maximum":16384},"minItems":2,"maxItems":2,"description":"drag: [x, y] to release at."},"dy":{"type":"integer","minimum":-100,"maximum":100,"description":"scroll: wheel clicks, positive is down."},"dx":{"type":"integer","minimum":-100,"maximum":100,"description":"scroll: wheel clicks, positive is right."},"text":{"type":"string","maxLength":8192,"description":"type: the text to type."},"delayMs":{"type":"integer","minimum":0,"maximum":200,"description":"type: pause between keystrokes."},"keys":{"type":"string","maxLength":512,"description":"key: xdotool names, e.g. \"ctrl+l\", \"Return\", \"alt+Tab\"."},"windowId":{"type":"string","description":"focus: an id from the window list."},"url":{"type":"string","maxLength":2048,"description":"open: an http(s) address to open in Chromium."},"argv":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":64,"description":"launch: a program and its arguments."}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"{ok: true}, or what was asked for: cursor {x, y}, windows {data}."}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop/recordings":{"post":{"operationId":"desktop.recordings.create","summary":"Record the desktop to an MP4 file.","description":"Starts recording the running desktop and answers once frames are being written. One recording at a time. The recorder uses one encoder thread at low priority, at most 30 fps; the file never exceeds maxMiB and recording stops while the sandbox's disk still has 256 MiB free. The file is on the sandbox's own disk and counts toward it; a sandbox keeps at most 8192 MiB of recordings. It is a fragmented MP4, so a recording cut short still plays. The first recording in a sandbox without ffmpeg installs it (up to a minute). Needs exec. 507 insufficient_storage when there is no room.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fps":{"type":"integer","minimum":1,"maximum":30,"description":"Frames a second. Default 10."},"maxSeconds":{"type":"integer","minimum":1,"maximum":7200,"description":"Stop after this much video. Default 1800."},"maxMiB":{"type":"integer","minimum":16,"maximum":4096,"description":"The file never grows past this. Default 512."},"crf":{"type":"integer","minimum":18,"maximum":45,"description":"Quality: 18 is sharp and large, 45 small. Default 30."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["starting","installing","recording","finished","failed"]},"path":{"type":"string","description":"The MP4 file in the sandbox."},"bytes":{"type":"integer","minimum":0},"seconds":{"type":"number"},"reason":{"type":["string","null"],"description":"Why it ended: stopped, max-seconds, max-bytes, disk-low (the disk reached its 256 MiB reserve), desktop-gone, error."},"processId":{"type":["string","null"]},"startedAt":{"type":["integer","null"]}},"required":["id","state","path","bytes"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"desktop.recordings.list","summary":"The desktop recordings in a sandbox, newest first.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["starting","installing","recording","finished","failed"]},"path":{"type":"string","description":"The MP4 file in the sandbox."},"bytes":{"type":"integer","minimum":0},"seconds":{"type":"number"},"reason":{"type":["string","null"],"description":"Why it ended: stopped, max-seconds, max-bytes, disk-low (the disk reached its 256 MiB reserve), desktop-gone, error."},"processId":{"type":["string","null"]},"startedAt":{"type":["integer","null"]}},"required":["id","state","path","bytes"],"additionalProperties":true}}},"required":["data"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop/recordings/{recordingId}":{"get":{"operationId":"desktop.recordings.get","summary":"One recording's state and size.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","pattern":"^rec-[a-z0-9]{8,32}$","description":"A recording's id."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["starting","installing","recording","finished","failed"]},"path":{"type":"string","description":"The MP4 file in the sandbox."},"bytes":{"type":"integer","minimum":0},"seconds":{"type":"number"},"reason":{"type":["string","null"],"description":"Why it ended: stopped, max-seconds, max-bytes, disk-low (the disk reached its 256 MiB reserve), desktop-gone, error."},"processId":{"type":["string","null"]},"startedAt":{"type":["integer","null"]}},"required":["id","state","path","bytes"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"desktop.recordings.delete","summary":"Stop a recording if it runs and delete its file.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","pattern":"^rec-[a-z0-9]{8,32}$","description":"A recording's id."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop/recordings/{recordingId}:stop":{"post":{"operationId":"desktop.recordings.stop","summary":"Stop a recording; answers when its file is complete.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","pattern":"^rec-[a-z0-9]{8,32}$","description":"A recording's id."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["starting","installing","recording","finished","failed"]},"path":{"type":"string","description":"The MP4 file in the sandbox."},"bytes":{"type":"integer","minimum":0},"seconds":{"type":"number"},"reason":{"type":["string","null"],"description":"Why it ended: stopped, max-seconds, max-bytes, disk-low (the disk reached its 256 MiB reserve), desktop-gone, error."},"processId":{"type":["string","null"]},"startedAt":{"type":["integer","null"]}},"required":["id","state","path","bytes"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/desktop/recordings/{recordingId}/video":{"get":{"operationId":"desktop.recordings.download","summary":"The recording as video/mp4.","description":"Streams the file; a recording still running is readable up to its last fragment. Needs read_file.","tags":["desktop"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","pattern":"^rec-[a-z0-9]{8,32}$","description":"A recording's id."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"video/mp4":{"schema":{"type":"string","contentMediaType":"video/mp4"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/browser:start":{"post":{"operationId":"browser.start","summary":"Start Chromium in the sandbox and return its CDP address.","description":"Starts Chromium with the Chrome DevTools Protocol on the sandbox's loopback (port 9222, for code inside the sandbox) and returns cdpUrl, a private wss address for agents outside it. Chromium comes from the host as a read-only disk, so a start in a new sandbox takes about 1 to 2 seconds and installs nothing. A sandbox from a custom image that is not Ubuntu 24.04 x86_64, or on a host without the layer, installs Chromium on its first start (about a minute, once; 409 browser_installing until then, which the SDKs wait for). Idempotent: a running browser is returned as it is. Needs exec.","tags":["browser"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"headless":{"type":"boolean","description":"true (the default): no window. false: on the sandbox's desktop, which this starts, with a live view."},"width":{"type":"integer","minimum":240,"maximum":3840,"description":"Window width in pixels. Default 1280."},"height":{"type":"integer","minimum":240,"maximum":2160,"description":"Window height in pixels. Default 800."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"running":{"type":"boolean"},"headless":{"type":"boolean"},"version":{"type":"string","description":"Chromium's version, e.g. \"Chrome/154.0.8037.92\"."},"cdpUrl":{"type":"string","description":"The browser's DevTools WebSocket, with its private preview token: give it to Playwright's connectOverCDP, puppeteer.connect({browserWSEndpoint}), browser-use or Stagehand as it is."},"httpUrl":{"type":"string","description":"The DevTools HTTP endpoint (json/version and the rest); send headers with it."},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expiresAt":{"type":["string","null"],"description":"When the token in cdpUrl ends; GET the browser again for a fresh one."},"streamUrl":{"type":"string","description":"headless: false only: the desktop's live view."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"description":"browser:start only: the sandbox's memory, which is the browser's."},"hint":{"type":"string","description":"browser:start only, under 2048 MiB: heavy apps such as Google Sheets, YouTube and StackBlitz need a 2 GiB sandbox; 1 GiB suits light pages."}},"required":["running"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/browser":{"get":{"operationId":"browser.get","summary":"Whether the sandbox's browser runs, and its CDP address with a fresh token.","tags":["browser"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"running":{"type":"boolean"},"headless":{"type":"boolean"},"version":{"type":"string","description":"Chromium's version, e.g. \"Chrome/154.0.8037.92\"."},"cdpUrl":{"type":"string","description":"The browser's DevTools WebSocket, with its private preview token: give it to Playwright's connectOverCDP, puppeteer.connect({browserWSEndpoint}), browser-use or Stagehand as it is."},"httpUrl":{"type":"string","description":"The DevTools HTTP endpoint (json/version and the rest); send headers with it."},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expiresAt":{"type":["string","null"],"description":"When the token in cdpUrl ends; GET the browser again for a fresh one."},"streamUrl":{"type":"string","description":"headless: false only: the desktop's live view."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"description":"browser:start only: the sandbox's memory, which is the browser's."},"hint":{"type":"string","description":"browser:start only, under 2048 MiB: heavy apps such as Google Sheets, YouTube and StackBlitz need a 2 GiB sandbox; 1 GiB suits light pages."}},"required":["running"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/browser:stop":{"post":{"operationId":"browser.stop","summary":"Stop the sandbox's browser.","tags":["browser"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"stopped":{"type":"boolean"}},"required":["stopped"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/mcp/catalog":{"get":{"operationId":"mcp.catalog","summary":"Well-known MCP servers you can start in a sandbox with one call.","description":"Each entry names its licence (all MIT or Apache-2.0), the pinned version, the settings it needs (secret ones come from Runtime secrets) and the hosts it calls.","tags":["mcp"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["data"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/mcp":{"post":{"operationId":"mcp.start","summary":"Start MCP servers in a sandbox and get the URLs your agent connects to.","description":"Starts the gateway in the sandbox and answers once it listens: each server has a Streamable HTTP URL, and every request needs the Authorization header returned. Servers install in the background (npm, uv or a pinned release, checked against its SHA-256) and report installing, then ready; poll GET .../mcp. They run as the sandbox's user behind its own network rules, which this never changes: a host the rules refuse is a warning. Needs exec.","tags":["mcp"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A catalog server's id, from GET /v1/mcp/catalog."},"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"Its name in the URL (/mcp/<name>). The id by default; required for command."},"secrets":{"type":"object","additionalProperties":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$"},"description":"A setting the catalog marks secret, to the Runtime secret that fills it: {\"GITHUB_PERSONAL_ACCESS_TOKEN\": \"GITHUB_TOKEN\"}. The server sees only a placeholder; the egress proxy puts the value into its HTTPS requests to the secret's hosts."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":8192},"maxProperties":32,"description":"Plain settings. Proxy variables cannot be set."},"options":{"type":"object","additionalProperties":{"type":"string","maxLength":512}},"command":{"type":"array","items":{"type":"string","maxLength":4096},"minItems":1,"maxItems":64,"description":"Instead of id: your own stdio MCP server, a program in the sandbox and its arguments."}}},"minItems":1,"maxItems":8},"port":{"type":"integer","minimum":1024,"maximum":65535,"description":"The gateway's port in the sandbox. Default 8765."},"replace":{"type":"boolean","description":"Stop a gateway already running and start this one."},"public":{"type":"boolean","description":"Serve the gateway at a public preview: URLs with no link token that never expire, for an agent to be configured with once. The Authorization header still guards every request, and it is kept across starts (after a restart, or with replace) until DELETE .../mcp. Needs an account with a kept top-up, as any public preview."}},"required":["servers"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"running":{"type":"boolean"},"port":{"type":["integer","null"]},"public":{"type":"boolean","description":"The URLs are a public preview: no link token, no expiry."},"token":{"type":"string","description":"Send it as Authorization: Bearer <token>."},"headers":{"type":"object","description":"The headers every MCP request needs."},"urlExpiresAt":{"type":["string","null"],"description":"When the URLs' link token expires; read again for new ones. null for public URLs, which do not expire."},"servers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["installing","ready","failed"]},"message":{"type":["string","null"]},"url":{"type":["string","null"],"description":"The server's Streamable HTTP endpoint."}},"required":["name","status"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["running","servers"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"mcp.get","summary":"The sandbox's MCP servers, their state and fresh URLs.","tags":["mcp"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"running":{"type":"boolean"},"port":{"type":["integer","null"]},"public":{"type":"boolean","description":"The URLs are a public preview: no link token, no expiry."},"token":{"type":"string","description":"Send it as Authorization: Bearer <token>."},"headers":{"type":"object","description":"The headers every MCP request needs."},"urlExpiresAt":{"type":["string","null"],"description":"When the URLs' link token expires; read again for new ones. null for public URLs, which do not expire."},"servers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["installing","ready","failed"]},"message":{"type":["string","null"]},"url":{"type":["string","null"],"description":"The server's Streamable HTTP endpoint."}},"required":["name","status"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["running","servers"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"mcp.stop","summary":"Stop the sandbox's MCP gateway and every server it runs.","description":"Its token is forgotten too: the next start hands out a new one. A public preview of its port stays shared until you remove it.","tags":["mcp"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"stopped":{"type":"boolean"}},"required":["stopped"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/referrals":{"get":{"operationId":"referrals.get","summary":"Your referral link, the companies that signed up with it, and the credit earned.","description":"A company that signs up with your link has every payment in its first 30 days matched, up to $1,000 in total, and you get the same, payment by payment; its first payment of at least $10 gives each side at least $25. Then, for 12 months, you earn 10% of what it spends from credit it paid for, credited monthly. You earn at most $50,000 a calendar year, matches and share together. Money is integer microdollars in strings.","tags":["referrals"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Your organization's referral code. Permanent."},"link":{"type":"string","description":"Share this: https://withruntime.com/r/<code>."},"rewardMicros":{"type":"string","pattern":"^[0-9]+$","description":"The least each side gets on the referred company's first qualifying payment: a smaller one is matched up to this. Integer microdollars, as a string."},"maxRewardMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most each side gets per referred company, all its matched payments together. Integer microdollars, as a string."},"minPurchaseMicros":{"type":"string","pattern":"^[0-9]+$","description":"The smallest payment a referral matches. Integer microdollars, as a string."},"yearlyCapMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most referral credit, matches and share together, you can earn in one calendar year (UTC). Integer microdollars, as a string."},"enabled":{"type":"boolean","description":"False while the program is paused."},"year":{"type":"integer","minimum":2026,"maximum":9999},"signedUp":{"type":"integer","minimum":0,"description":"Companies that signed up with your link."},"pending":{"type":"integer","minimum":0,"description":"Signed up, first qualifying payment not made yet."},"paid":{"type":"integer","minimum":0,"description":"Referrals with a payment matched: both sides credited."},"capped":{"type":"integer","minimum":0,"description":"Paid, but the yearly cap left you less than a whole match."},"reversed":{"type":"integer","minimum":0,"description":"Every matched payment was refunded or disputed below the minimum, so the matches were taken back."},"earnedMicros":{"type":"string","pattern":"^[0-9]+$","description":"Referral credit you kept, all time: matches and share. Integer microdollars, as a string."},"earnedThisYearMicros":{"type":"string","pattern":"^[0-9]+$","description":"Referral credit counted against this year's cap. Integer microdollars, as a string."},"capRemainingMicros":{"type":"string","pattern":"^[0-9]+$","description":"What you can still earn this year. Integer microdollars, as a string."},"payingCompanies":{"type":"integer","minimum":0,"description":"Referred companies with a matched payment still standing."},"shareEarnedMicros":{"type":"string","pattern":"^[0-9]+$","description":"Share credit you kept, all time: credited, less what lost disputes took back. Integer microdollars, as a string."},"shareBasisPoints":{"type":"integer","minimum":0,"maximum":10000,"description":"Your share of what a referred company spends from credit it paid for, in basis points: 1000 is 10%."},"shareMonths":{"type":"integer","minimum":1,"description":"How long the share runs from a company's first matched payment."},"windowDays":{"type":"integer","minimum":1,"description":"How long after sign-up a referred company's payments are matched."},"referredBy":{"type":["object","null"],"description":"Whether your organization signed up through someone's link, and the credit it got. Null when it did not.","properties":{"status":{"type":"string","enum":["pending","paid","refused","reversed"]},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The referral credit your organization received. Integer microdollars, as a string."}}}},"required":["code","link","rewardMicros","maxRewardMicros","minPurchaseMicros","yearlyCapMicros","enabled","year","signedUp","pending","paid","capped","reversed","earnedMicros","earnedThisYearMicros","capRemainingMicros","referredBy","payingCompanies","shareEarnedMicros","shareBasisPoints","shareMonths","windowDays"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/usage/compare":{"get":{"operationId":"usage.compare","summary":"What your sandboxes would have cost at a rival: the same vCPUs, memory and running time at its published rates.","description":"Prices this key's settled sandbox usage over the last `days` (default 30, at most 90) at the rates each sandbox was quoted (a sandbox free usage paid for at the standard rates, since it charged nothing; `usage.trialSandboxes` counts them), and the identical sandboxes at the rival's published list rates, which come from the same table the comparison pages use and name the date they were checked. Returns both costs, the saving and a 30-day projection. With no usage yet it prices a stated example workload and says so (`basis: example`); quote a saving to the owner only after the project's real job has run (`basis: usage`). Compute only: storage, network, plan fees and free allowances are left out. Also returns the switch on record and the welcome match's state. Money is integer microdollars in strings.","tags":["switching"],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly-sprites","fly-machines","blaxel","codesandbox","morph","northflank","runloop","lambda-microvms","freestyle","prime","fly"],"description":"The rival to price against. fly is Sprites; fly-machines is Machines."},"description":"The rival to price against. fly is Sprites; fly-machines is Machines."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"description":"The window, in days. Default 30."},"description":"The window, in days. Default 30."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly-sprites","fly-machines","blaxel","codesandbox","morph","northflank","runloop","lambda-microvms","freestyle","prime","fly"]},"rival":{"type":"object","properties":{"name":{"type":"string"},"checked":{"type":"string","description":"ISO date the rival's published rates were read."},"rates":{"type":"array","items":{"type":"string"},"description":"The rival's rates, as it publishes them."},"planFee":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"],"additionalProperties":false}}},"required":["name","checked","rates","planFee","sources"],"additionalProperties":false},"basis":{"type":"string","enum":["usage","example"],"description":"usage: your settled sandboxes in the window. example: none yet, so a stated example workload is priced instead."},"window":{"type":"object","properties":{"days":{"type":"integer","minimum":1},"from":{"type":"string"},"to":{"type":"string"}},"required":["days","from","to"],"additionalProperties":false},"usage":{"type":"object","properties":{"sandboxes":{"type":"integer","minimum":0},"runSeconds":{"type":"number","minimum":0},"activeCpuSeconds":{"type":"number","minimum":0},"unpricedSandboxes":{"type":"integer","minimum":0},"trialSandboxes":{"type":"integer","minimum":0,"description":"Of sandboxes, how many free usage paid for (the free usage, or free hours given before 5 October 2026), which charged nothing for them; runtimeMicros prices them at Runtime's standard rates."},"trialRunSeconds":{"type":"number","minimum":0,"description":"The running time free usage paid for."}},"required":["sandboxes","runSeconds","activeCpuSeconds","unpricedSandboxes","trialSandboxes","trialRunSeconds"],"additionalProperties":false},"runtimeMicros":{"type":"string","pattern":"^[0-9]+$","description":"What the usage costs on Runtime on paid credit: each paid sandbox at the rates it was quoted, and a sandbox free usage paid for at the standard rates, not zero. Integer microdollars, as a string (1,000,000 = $1)."},"rivalMicros":{"type":"string","pattern":"^[0-9]+$","description":"What the same sandboxes cost at the rival's published list rates. Integer microdollars, as a string (1,000,000 = $1)."},"savingMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"Rival less Runtime; negative when the rival costs less. Integer microdollars, as a string (1,000,000 = $1)."},"savingPercent":{"type":["number","null"],"description":"The saving as a percentage of the rival's cost."},"perMonth":{"type":["object","null"],"description":"The same figures scaled to 30 days from the days the usage covers. Null for the example.","properties":{"fromDays":{"type":"number"},"runtimeMicros":{"type":"string","pattern":"^[0-9]+$","description":"Runtime, per 30 days. Integer microdollars, as a string (1,000,000 = $1)."},"rivalMicros":{"type":"string","pattern":"^[0-9]+$","description":"The rival, per 30 days. Integer microdollars, as a string (1,000,000 = $1)."},"savingMicros":{"type":"string","pattern":"^-?[0-9]+$","description":"The saving, per 30 days. Integer microdollars, as a string (1,000,000 = $1)."}}},"note":{"type":"string","description":"What was compared, at which rates, and what was left out."},"switching":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the programme is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]}},"eligible":{"type":"boolean","description":"Whether this organization can record a switch now: none recorded yet, and no top-up paid yet."},"switch":{"type":["object","null"],"description":"The switch this organization recorded, or null when it has not.","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: no payment decided yet. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: see refusedReason. reversed: every matched payment was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud","too_late",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the match is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"endsAt":{"type":"string","format":"date-time","description":"When the offer ends: 30 days after the organization signed up."},"eligible":{"type":"boolean","description":"Whether credit added now would be matched: some of maxMicros is left and the offer is open."},"toppedUp":{"type":"boolean","description":"Whether credit has been added."},"status":{"type":["string","null"],"enum":["pending","paid","superseded","refused","reversed",null],"description":"Null until a payment is decided. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: the latest payment was not matched. reversed: every matched payment was refunded or disputed."},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."},"usedMicros":{"type":"string","pattern":"^[0-9]+$","description":"The part of maxMicros used: creditMicros. Integer microdollars, as a string (1,000,000 = $1)."},"leftMicros":{"type":"string","pattern":"^[0-9]+$","description":"What credit added now could still get; 0 once the offer ends. Integer microdollars, as a string (1,000,000 = $1)."}},"required":["enabled","maxMicros","endsAt","eligible","toppedUp","status","creditMicros","usedMicros","leftMicros"],"additionalProperties":false}},"required":["enabled","maxMicros","providers","eligible","switch","welcome"],"additionalProperties":false}},"required":["provider","rival","basis","window","usage","runtimeMicros","rivalMicros","savingMicros","savingPercent","perMonth","note","switching"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/switching":{"get":{"operationId":"switching.get","summary":"The switch on record and the welcome match: whether you can still record a switch, and what the match paid.","description":"Credit an organization adds within 30 days of signing up is matched, up to $1,000 in total across its payments, as each payment settles; `welcome` says until when, how much is used and left, and what it paid. Record the rival you are leaving with POST /v1/switching before the first top-up. Money is integer microdollars in strings.","tags":["switching"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the programme is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]}},"eligible":{"type":"boolean","description":"Whether this organization can record a switch now: none recorded yet, and no top-up paid yet."},"switch":{"type":["object","null"],"description":"The switch this organization recorded, or null when it has not.","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: no payment decided yet. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: see refusedReason. reversed: every matched payment was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud","too_late",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the match is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"endsAt":{"type":"string","format":"date-time","description":"When the offer ends: 30 days after the organization signed up."},"eligible":{"type":"boolean","description":"Whether credit added now would be matched: some of maxMicros is left and the offer is open."},"toppedUp":{"type":"boolean","description":"Whether credit has been added."},"status":{"type":["string","null"],"enum":["pending","paid","superseded","refused","reversed",null],"description":"Null until a payment is decided. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: the latest payment was not matched. reversed: every matched payment was refunded or disputed."},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."},"usedMicros":{"type":"string","pattern":"^[0-9]+$","description":"The part of maxMicros used: creditMicros. Integer microdollars, as a string (1,000,000 = $1)."},"leftMicros":{"type":"string","pattern":"^[0-9]+$","description":"What credit added now could still get; 0 once the offer ends. Integer microdollars, as a string (1,000,000 = $1)."}},"required":["enabled","maxMicros","endsAt","eligible","toppedUp","status","creditMicros","usedMicros","leftMicros"],"additionalProperties":false}},"required":["enabled","maxMicros","providers","eligible","switch","welcome"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"switching.record","summary":"Record the rival this organization is switching from, before its first top-up.","description":"Once per organization, and only before its first top-up is paid. It records where the organization came from; the reward is the welcome match: credit added within 30 days of signing up is matched, up to $1,000 in total, as each payment settles, and a referral, which matches the same payments and is never less, applies instead, never both. A refund or chargeback of a payment takes back that payment's match. Recording the same provider again answers the same summary; a different one is refused with 409.","tags":["switching"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]}},"required":["provider"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the programme is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]}},"eligible":{"type":"boolean","description":"Whether this organization can record a switch now: none recorded yet, and no top-up paid yet."},"switch":{"type":["object","null"],"description":"The switch this organization recorded, or null when it has not.","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: no payment decided yet. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: see refusedReason. reversed: every matched payment was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud","too_late",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}},"welcome":{"type":"object","properties":{"enabled":{"type":"boolean","description":"False while the match is paused."},"maxMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most the organization's payments are matched to, in total. Integer microdollars, as a string (1,000,000 = $1)."},"endsAt":{"type":"string","format":"date-time","description":"When the offer ends: 30 days after the organization signed up."},"eligible":{"type":"boolean","description":"Whether credit added now would be matched: some of maxMicros is left and the offer is open."},"toppedUp":{"type":"boolean","description":"Whether credit has been added."},"status":{"type":["string","null"],"enum":["pending","paid","superseded","refused","reversed",null],"description":"Null until a payment is decided. paid: some payment's match is kept. superseded: a referral matches the payments instead, which is never less. refused: the latest payment was not matched. reversed: every matched payment was refunded or disputed."},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The matches this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."},"usedMicros":{"type":"string","pattern":"^[0-9]+$","description":"The part of maxMicros used: creditMicros. Integer microdollars, as a string (1,000,000 = $1)."},"leftMicros":{"type":"string","pattern":"^[0-9]+$","description":"What credit added now could still get; 0 once the offer ends. Integer microdollars, as a string (1,000,000 = $1)."}},"required":["enabled","maxMicros","endsAt","eligible","toppedUp","status","creditMicros","usedMicros","leftMicros"],"additionalProperties":false}},"required":["enabled","maxMicros","providers","eligible","switch","welcome"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/limits":{"get":{"operationId":"limits.get","summary":"What this key may do, its agent's daily spending limit with what is left, the machine time the account can still run without credit, the account's limits with what it uses of each, and its credit with how long it lasts.","description":"A key is full, read (read-only: every read, no write) or selected. An owner may set a daily limit on the agent a key belongs to, at https://withruntime.com/account/keys; a key can read it here but never change it. When a create, wake, extension or renewal would take the agent past it, the request fails with spending_limit_reached (402). The account's limits (sandboxes at once, their vCPUs and memory, volumes, snapshots and the rest) come with what it uses of each now, the numbers a create past one is refused quota_exceeded by. credit says what is left, how many days it lasts at this month's pace, and who adds more: an account opened with a wallet that no person pays for adds its own with POST /v1/billing/topups. Money is integer microdollars in strings.","tags":["limits"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"access":{"type":["string","null"],"enum":["full","read","selected",null],"description":"full: every action in every product. read: every read and nothing else (a read-only key). selected: the actions the key names."},"daily":{"type":"object","properties":{"limitMicros":{"type":["string","null"],"pattern":"^[0-9]+$","description":"The most this agent may commit in any 24 hours. Integer microdollars, as a string, or null when the agent has no daily limit."},"usedMicros":{"type":"string","pattern":"^[0-9]+$","description":"What this agent committed in the last 24 hours: charges settled plus money still on hold. Integer microdollars, as a string (1,000,000 = $1)."},"remainingMicros":{"type":["string","null"],"pattern":"^[0-9]+$","description":"What is left under the limit right now. Integer microdollars, as a string, or null when the agent has no daily limit."},"window":{"type":"string","const":"24h","description":"The limit counts a rolling 24 hours."}},"required":["limitMicros","usedMicros","remainingMicros","window"],"additionalProperties":false},"trial":{"type":["object","null"],"description":"Machine time an account without credit can still run, in milliseconds, the same figures as GET /v1/usage, or null when the account has none. totalMs, usedMs and reservedMs count free hours an account was given before 5 October 2026; availableMs is the larger of those hours left and this month's free usage, as time at the largest size an account without credit runs (2 vCPU, 4096 MiB). A sandbox that has not ended holds its whole lease in reservedMs; what it did not use comes back when it ends.","properties":{"totalMs":{"type":"integer","minimum":0,"description":"Free hours given before 5 October 2026; 0 for an account given none."},"usedMs":{"type":"integer","minimum":0,"description":"Of those hours, used by sandboxes that ended."},"reservedMs":{"type":"integer","minimum":0,"description":"Of those hours, held for sandboxes that have not ended."},"availableMs":{"type":"integer","minimum":0,"description":"What a new sandbox without credit can still use: the larger of total - used - reserved and this month's free usage."},"offer":{"type":"string","enum":["hours","monthly"],"description":"hours: the account was given free hours before 5 October 2026 and keeps them. monthly: free usage every month only."},"renewsAt":{"type":"string","format":"date-time","description":"When the free usage renews: the 1st of next month, 00:00 UTC."}},"required":["totalMs","usedMs","reservedMs","availableMs","offer","renewsAt"],"additionalProperties":false},"account":{"type":["array","null"],"description":"Every limit the account is held to, with what it uses of each now: the same numbers that refuse a create with quota_exceeded (its details.limit names the row), as https://withruntime.com/account/limits shows them. Null when they can't be read.","items":{"type":"object","properties":{"limit":{"type":"string","description":"<kind>.<dimension>, such as sandbox.count, sandbox.vcpu, sandbox.memory_mib or volume.count."},"label":{"type":"string","description":"The limit in words."},"unit":{"type":"string","enum":["count","mib"],"description":"What max and used count: things, or MiB."},"max":{"type":"integer","minimum":0,"description":"The most the account may hold."},"used":{"type":"integer","minimum":0,"description":"What it holds now."}},"required":["limit","label","unit","max","used"],"additionalProperties":false}},"credit":{"type":"object","properties":{"availableMicros":{"type":"string","pattern":"^[0-9]+$","description":"The account's credit left now, as GET /v1/usage's available: credited less spent, expired and held. Integer microdollars, as a string (1,000,000 = $1)."},"dailyPaceMicros":{"type":["string","null"],"pattern":"^[0-9]+$","description":"A day of usage at this month's pace (settled usage so far over the time the month has run; last month's while this one is under three days old). Integer microdollars, as a string, or null when nothing is being spent."},"runwayDays":{"type":["integer","null"],"minimum":0,"description":"Whole days the credit lasts at that pace, rounded down; null when nothing is being spent. The console's Home says the same."},"lowBelowDays":{"type":"integer","minimum":1,"description":"Credit lasting fewer days than this is low: the credit.low webhook and the owners' notice are sent then."},"state":{"type":"string","enum":["ok","low","empty"],"description":"low: under lowBelowDays left at this pace. empty: none left; running paid sandboxes pause and new ones are refused."},"addedBy":{"type":"string","enum":["owner","agent"],"description":"Who adds credit. owner: a person, on the website (https://withruntime.com/account/billing). agent: the account was opened with a wallet and no person pays for it, so its own agents add credit with POST /v1/billing/topups (`npx withruntime billing topup <usd>`)."}},"required":["availableMicros","dailyPaceMicros","runwayDays","lowBelowDays","state","addedBy"],"additionalProperties":false}},"required":["access","daily","trial","account","credit"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/keys":{"post":{"operationId":"keys.create","summary":"Make a key with this key, with no browser: a key per worker in an agent swarm.","description":"Needs a full-access key made by an owner or admin (a wallet account's key is one). A read-only key, a developer's or one in a compartment cannot. The new key never has more than this one: account-wide only from an account-wide key, this key's expiry and per-request cap, and when this key has a daily limit, the daily limits of the keys it made add up to at most its own. Each key gets its own agent, so its sandboxes, spend and audit rows are its own. At most 100 live keys made this way in an account, and 1,000 made in any 24 hours; revoke a worker's key when it is done. Every key made is in the audit log as key.created, naming the key that made it.","tags":["keys"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The key's name, and its agent's."},"access":{"type":"string","enum":["full","read"],"description":"full: every action in every product (the default). read: every read and nothing else."},"reach":{"type":"string","enum":["agent","account"],"description":"agent (the default): the key sees and acts on only what its own agent makes, so a worker sees only its own sandboxes. account: everything in the account; only an account-wide key can make one."},"dailyLimitMicros":{"type":["integer","null"],"minimum":1,"maximum":1000000000000,"description":"The most the key's agent may commit in any 24 hours, in integer microdollars (5000000 = $5), or null for none. Required when the making key has a limit; the limits of the keys a key made add up to at most its own. A read-only key takes none."},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[0-9a-fA-F-]{36}$"},"minItems":1,"maxItems":20,"description":"Limit the key to these sandboxes, by id: it is served only their own routes (get, metrics, stop, pause, wake, restart, exec, processes, files, interpreter) and only the actions given, and calls them by id. Not with access or reach. Only sandboxes this key acts on, outside every compartment."},"actions":{"type":"array","items":{"type":"string","enum":["get","create","stop","exec","read_file","write_file"]},"minItems":1,"maxItems":6,"description":"With sandboxes: what the key may do to them. get reads them; create starts, wakes and restarts them (never makes a sandbox), and is the one that spends; stop stops and pauses them; exec runs commands and processes; read_file and write_file reach their files."}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"The new key. Shown once: Runtime keeps only its hash. A retry with the same Idempotency-Key answers without it."},"keyId":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"The key's id."},"agentId":{"type":"string","description":"The new key's own agent: what it makes is that agent's."},"orgId":{"type":"string"},"name":{"type":"string"},"access":{"type":"string","enum":["full","read","selected"]},"reach":{"type":"string","enum":["agent","account","sandboxes"],"description":"agent: what its own agent makes. account: everything in the account. sandboxes: only the sandboxes it is limited to."},"dailyLimitMicros":{"type":["integer","null"],"minimum":1,"maximum":1000000000000,"description":"The most the key's agent may commit in any 24 hours, in integer microdollars (5000000 = $5), or null for none. Required when the making key has a limit; the limits of the keys a key made add up to at most its own. A read-only key takes none."},"sandboxes":{"type":["array","null"],"items":{"type":"string"},"description":"The sandboxes it is limited to, by id, or null for a key that is not limited."},"actions":{"type":["array","null"],"items":{"type":"string"},"description":"What it may do, for a key of named actions, or null for full and read."},"expires":{"type":["string","null"],"format":"date-time","description":"When it stops working: the making key's expiry, or null for until revoked."},"madeBy":{"type":"string","description":"The id of the key that made it."}},"required":["keyId","agentId","orgId","name","access","reach","dailyLimitMicros","expires","madeBy"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"keys.list","summary":"The keys this key made, and itself, with what each spent in the last 24 hours.","description":"Needs a full-access key made by an owner or admin (a wallet account's key is one). A read-only key, a developer's or one in a compartment cannot. An account-wide key lists every key in the account. Live keys first, then the newest; at most 1,000.","tags":["keys"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"keyId":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"The key's id."},"agentId":{"type":"string"},"name":{"type":"string"},"access":{"type":"string","enum":["full","read","selected"]},"reach":{"type":"string","enum":["agent","account","sandboxes"],"description":"agent: what its own agent makes. account: everything in the account. sandboxes: only the sandboxes it is limited to."},"dailyLimitMicros":{"type":["integer","null"]},"sandboxes":{"type":["array","null"],"items":{"type":"string"},"description":"The sandboxes it is limited to, by id, or null for a key that is not limited."},"actions":{"type":["array","null"],"items":{"type":"string"},"description":"What it may do, for a key of named actions, or null for full and read."},"dailyUsedMicros":{"type":"integer","minimum":0,"description":"What its agent committed in the last 24 hours: charges settled plus money on hold, as its daily limit counts."},"madeBy":{"type":["string","null"],"description":"The key that made it, or null for one made on the website."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["keyId","agentId","name","access","reach","dailyLimitMicros","dailyUsedMicros","madeBy","createdAt","expiresAt","revokedAt"],"additionalProperties":false}}},"required":["keys"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/keys/{id}":{"delete":{"operationId":"keys.revoke","summary":"Revoke this key, or a key it made: a worker's key when the worker is done.","description":"Needs a full-access key made by an owner or admin (a wallet account's key is one). A read-only key, a developer's or one in a compartment cannot. An account-wide key may revoke any key in the account. The key stops working within ten seconds; what its agent made keeps running until stopped.","tags":["keys"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"The key's id."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"The key's id."},"revokedAt":{"type":"string","format":"date-time"}},"required":["keyId","revokedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/egress-secrets":{"get":{"operationId":"secrets.list","summary":"The organization's secrets: names, hosts and placeholders, never values.","tags":["secrets"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"header":{"type":"string"},"format":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."},"reaches":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":1000000,"description":"How many sandboxes get it now."},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"The first 50 of their ids."}},"required":["count","sandboxes"],"additionalProperties":false,"description":"Present when only is set (in GET /v1/egress-secrets): the sandboxes that get the secret now, worked out as the servers do. A label matches only sandboxes made by a key outside every compartment. Absent: every sandbox of the organization gets it."},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. Without header, the proxy replaces it with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token) of HTTPS requests to the hosts; in the URL or any other header it goes out as it is."},"valueBytes":{"type":"integer","minimum":1,"maximum":8192},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/egress-secrets/{name}":{"put":{"operationId":"secrets.set","summary":"Store or replace a secret that sandboxes use without seeing it.","description":"Every sandbox of the organization (or, with only, the sandboxes it names by label or id) gets an environment variable of this name holding a placeholder. With header set, the egress proxy sets that header on every HTTPS request to the hosts and puts the value nowhere else; without, it replaces the placeholder with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token). A placeholder in the URL or any other header goes out as it is, so a server that echoes a request back never shows the value. With rules (an account with credit), only requests whose method and path a rule allows carry it. The value is sealed to the hosts' key and never returned. Replacing a secret keeps its placeholder. Takes effect on new connections within seconds.","tags":["secrets"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$","description":"The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores.","examples":["OPENAI_API_KEY","GITHUB_TOKEN"]}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":8192,"description":"The secret. Visible ASCII and spaces, at most 8 KiB. Stored sealed and never returned."},"hosts":{"type":"array","items":{"type":"string","maxLength":255,"pattern":"^(\\*\\.)?(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z][a-z0-9-]{0,62}$","description":"A host name, or *.domain for every name under it.","examples":["api.openai.com","*.github.com"]},"minItems":1,"maxItems":16,"description":"Where the value may go. The proxy puts it only into HTTPS requests to these hosts."},"header":{"type":"string","pattern":"^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$","description":"Optional. Set this header on every request to the hosts, replacing one the sandbox sent, so code needs no placeholder at all; the value then goes into this header and nowhere else. Without it, the placeholder is replaced only in a credential header: Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token.","examples":["Authorization","x-api-key"]},"format":{"type":"string","maxLength":256,"description":"Optional, with header. The header's value, with {value} where the secret goes. Default \"{value}\".","examples":["Bearer {value}","token {value}"]},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."}},"required":["value","hosts"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"header":{"type":"string"},"format":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."},"reaches":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":1000000,"description":"How many sandboxes get it now."},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"The first 50 of their ids."}},"required":["count","sandboxes"],"additionalProperties":false,"description":"Present when only is set (in GET /v1/egress-secrets): the sandboxes that get the secret now, worked out as the servers do. A label matches only sandboxes made by a key outside every compartment. Absent: every sandbox of the organization gets it."},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. Without header, the proxy replaces it with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token) of HTTPS requests to the hosts; in the URL or any other header it goes out as it is."},"valueBytes":{"type":"integer","minimum":1,"maximum":8192},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"secrets.delete","summary":"Delete a secret. Its sealed value is erased; the placeholder stops working.","tags":["secrets"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$","description":"The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores.","examples":["OPENAI_API_KEY","GITHUB_TOKEN"]}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"deleted":{"type":"boolean"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/egress-secrets/{name}/sandboxes":{"put":{"operationId":"secrets.scope","summary":"Change which sandboxes get a secret, without its value.","description":"The body is the secret's only: labels (selectors, any one matching) and/or sandboxes (ids). {} gives it to every sandbox of the organization. A sandbox leaving the scope stops carrying the value on its next request within seconds; one entering it has it as quickly.","tags":["secrets"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$","description":"The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores.","examples":["OPENAI_API_KEY","GITHUB_TOKEN"]}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"header":{"type":"string"},"format":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."},"reaches":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":1000000,"description":"How many sandboxes get it now."},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"The first 50 of their ids."}},"required":["count","sandboxes"],"additionalProperties":false,"description":"Present when only is set (in GET /v1/egress-secrets): the sandboxes that get the secret now, worked out as the servers do. A label matches only sandboxes made by a key outside every compartment. Absent: every sandbox of the organization gets it."},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. Without header, the proxy replaces it with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token) of HTTPS requests to the hosts; in the URL or any other header it goes out as it is."},"valueBytes":{"type":"integer","minimum":1,"maximum":8192},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/egress-secrets/{name}/rules":{"put":{"operationId":"secrets.narrow","summary":"Narrow where a secret goes, without its value.","description":"Sets the secret's hosts and/or rules to ones that let the value go nowhere new: every host one of its hosts names (a.example.com or *.a.example.com under *.example.com), and every method and path a rule allows one its rules allow now (a secret without rules allows every request, so any rules narrow it). Either left out stays as it is. Anything wider is refused (400, invalid_request): a new place could learn the value, so widening needs the value (PUT /v1/egress-secrets/{name}). Recorded in the audit log as an update with narrowed. Takes effect on new connections within seconds.","tags":["secrets"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$","description":"The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores.","examples":["OPENAI_API_KEY","GITHUB_TOKEN"]}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hosts":{"type":"array","items":{"type":"string","maxLength":255,"pattern":"^(\\*\\.)?(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z][a-z0-9-]{0,62}$","description":"A host name, or *.domain for every name under it.","examples":["api.openai.com","*.github.com"]},"minItems":1,"maxItems":16,"description":"Where the value may go. The proxy puts it only into HTTPS requests to these hosts."},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"header":{"type":"string"},"format":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{1,16}$"},"minItems":1,"maxItems":16,"description":"Optional. The methods allowed; every method when absent.","examples":[["GET","HEAD"]]},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"minItems":1,"maxItems":16,"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.","examples":[["/v1/chat/completions"],["/repos/acme/*"]]}},"required":["paths"],"additionalProperties":false},"minItems":1,"maxItems":16,"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string","maxLength":256},"minProperties":1,"maxProperties":8,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"minItems":1,"maxItems":8,"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.","examples":[[{"role":"hub"}],[{"role":"hub"},{"purpose":"agent"}]]},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"minItems":1,"maxItems":100,"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"required":[],"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."},"reaches":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":1000000,"description":"How many sandboxes get it now."},"sandboxes":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"The first 50 of their ids."}},"required":["count","sandboxes"],"additionalProperties":false,"description":"Present when only is set (in GET /v1/egress-secrets): the sandboxes that get the secret now, worked out as the servers do. A label matches only sandboxes made by a key outside every compartment. Absent: every sandbox of the organization gets it."},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. Without header, the proxy replaces it with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token) of HTTPS requests to the hosts; in the URL or any other header it goes out as it is."},"valueBytes":{"type":"integer","minimum":1,"maximum":8192},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/networks/upstream-proxy":{"get":{"operationId":"networks.upstreamProxy.get","summary":"The proxy your sandboxes' outbound connections go through, if you set one.","tags":["networks"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The proxy: http://host:port or https://host:port.","examples":["http://proxy.example.com:3128"]},"secret":{"type":"string","description":"The secret whose value is sent as Proxy-Authorization, such as Basic dXNlcjpwYXNz. Its hosts must name the proxy's host."},"hosts":{"type":"array","items":{"type":"string"},"description":"The destinations that go through the proxy; every destination when absent."},"updatedAt":{"type":"string","format":"date-time"}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"put":{"operationId":"networks.upstreamProxy.set","summary":"Send your sandboxes' outbound connections through your own proxy.","description":"Needs a kept top-up. After Runtime's own network rules allow a connection, the host's proxy reaches it with CONNECT through yours, so your proxy's controls and logs apply and the traffic leaves from your proxy's address. Secrets are still put in by Runtime before the bytes enter your proxy's tunnel. If your proxy refuses or cannot be reached, the connection fails with upstream-proxy-failed; it never falls back to a direct connection. UDP to a covered host is refused. Takes effect on new connections within seconds.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":300,"description":"http://host:port or https://host:port. An https proxy's certificate must verify against the public roots.","examples":["http://proxy.example.com:3128"]},"secret":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]{0,127}$","description":"Optional. One of your secrets, sent as the Proxy-Authorization header's whole value. Its hosts must name the proxy's host.","examples":["PROXY_AUTH"]},"hosts":{"type":"array","items":{"type":"string","maxLength":255,"pattern":"^(\\*\\.)?(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z][a-z0-9-]{0,62}$"},"minItems":1,"maxItems":16,"description":"Optional. Only connections to these hosts (or *.domain) go through the proxy; the rest leave as before. Every connection when absent.","examples":[["*.internal.example.com"]]}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The proxy: http://host:port or https://host:port.","examples":["http://proxy.example.com:3128"]},"secret":{"type":"string","description":"The secret whose value is sent as Proxy-Authorization, such as Basic dXNlcjpwYXNz. Its hosts must name the proxy's host."},"hosts":{"type":"array","items":{"type":"string"},"description":"The destinations that go through the proxy; every destination when absent."},"updatedAt":{"type":"string","format":"date-time"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"operationId":"networks.upstreamProxy.remove","summary":"Stop sending connections through your proxy.","tags":["networks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"enforced":{"type":"boolean","description":"True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/usage/export":{"get":{"operationId":"usage.export","summary":"Export settled usage for every visible product and resource over a UTC date range.","description":"Selects settlement timestamps in [since, until), with exact decimal strings for money and quantities. Pending holds are excluded. Each page contains data, nextCursor and server-rendered CSV; concatenate CSV pages in order, with the header on the first page only. Follow nextCursor with the same range. Pages use deterministic timestamp/id ordering and preserve microseconds; they are live reads, not a retained database snapshot. Every page rechecks the key's usage permission and tenant visibility. finalThrough is a moment before which no row can still appear or change; a row's final is true once its resource is deleted and every charge it will have is settled before finalThrough.","tags":["account"],"parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","minLength":20,"maxLength":24,"description":"Inclusive UTC ISO timestamp with Z, for example 2026-09-01T00:00:00.000Z."},"description":"Inclusive UTC ISO timestamp with Z, for example 2026-09-01T00:00:00.000Z."},{"name":"until","in":"query","required":false,"schema":{"type":"string","minLength":20,"maxLength":24,"description":"Exclusive UTC ISO timestamp with Z."},"description":"Exclusive UTC ISO timestamp with Z."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string"},"until":{"type":"string"},"nextCursor":{"type":["string","null"]},"finalThrough":{"type":["string","null"]},"csv":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"intervalId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"resourceId":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"name":{"type":["string","null"]},"kind":{"type":"string"},"meter":{"type":"string"},"fundedBy":{"type":"string","enum":["credit","trial","allowance"]},"startsAt":{"type":"string"},"endsAt":{"type":"string"},"settledAt":{"type":"string"},"billedMilliseconds":{"type":["string","null"],"pattern":"^[0-9]+$"},"chargedMicros":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"quotedRates":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"unit":{"type":"string"},"rateMicros":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."}},"required":["component","unit","rateMicros"],"additionalProperties":false}},"measurementsJson":{"type":["string","null"]},"evidence":{"type":["string","null"],"enum":["measured","partial","missing",null]},"final":{"type":"boolean"}},"required":["intervalId","resourceId","name","kind","meter","fundedBy","startsAt","endsAt","settledAt","billedMilliseconds","chargedMicros","quotedRates","measurementsJson","evidence","final"],"additionalProperties":false}}},"required":["since","until","data","nextCursor","finalThrough","csv"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/usage/requests":{"get":{"operationId":"usage.requests","summary":"The account's recorded API calls and error rates by operation.","description":"Authenticated API answers only, grouped by operation across hourly buckets. The current hour is partial; counts are written about once a minute. Calls are exact decimal strings; clientErrors counts 4xx, serverErrors counts 5xx, errorPercent counts both and is null when no calls were recorded. The read checks the current key's usage permission and returns only its organization's counts.","tags":["account"],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"24h"}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string","enum":["24h","7d","30d","90d"]},"since":{"type":"string"},"until":{"type":"string"},"calls":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"clientErrors":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"serverErrors":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"errorPercent":{"type":["number","null"],"description":"Share of recorded authenticated answers with status 400 or above; null with no calls."},"operations":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string"},"calls":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"clientErrors":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"serverErrors":{"type":"string","pattern":"^[0-9]+$","description":"Exact integer count, as a decimal string."},"errorPercent":{"type":["number","null"],"description":"Share of answers with status 400 or above; null with no calls."}},"required":["operation","calls","clientErrors","serverErrors","errorPercent"],"additionalProperties":false}}},"required":["range","since","until","calls","clientErrors","serverErrors","errorPercent","operations"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/metrics":{"get":{"operationId":"sandboxes.metrics","summary":"A sandbox's CPU, memory and measured waiting over time, and its latest reading.","description":"CPU is measured, not estimated: the machine's CPU time between two host readings, as a percent of the sandbox's vCPUs and as cores. Memory is the machine's resident memory. The host reads every running sandbox every minute by default. range picks the window and bucket: 15m (10 s buckets), 1h (20 s buckets), 6h (120 s buckets), 24h (480 s buckets), 7d (3600 s buckets), 30d (3600 s buckets). Readings are kept 24 hours; hourly averages and peaks 30 days. A paused or stopped sandbox has no new readings.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["15m","1h","6h","24h","7d","30d"],"default":"1h"}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"sandboxId":{"type":"string"},"range":{"type":"string","enum":["15m","1h","6h","24h","7d","30d"]},"stepSeconds":{"type":"integer","minimum":1},"since":{"type":"string"},"until":{"type":"string"},"vcpu":{"type":"integer","minimum":1},"memoryLimitBytes":{"type":"integer","minimum":0},"diskLimitBytes":{"type":"integer","minimum":0},"state":{"type":"string"},"latest":{"oneOf":[{"type":"object","properties":{"at":{"type":"string","description":"Start of the bucket, ISO 8601."},"cpuPercent":{"type":["number","null"],"description":"Average CPU, percent of all the sandbox's vCPUs (0-100)."},"cpuCores":{"type":["number","null"],"description":"The same average as a number of cores."},"cpuPeakPercent":{"type":["number","null"],"description":"The busiest interval between two readings in the bucket."},"cpuWaitPercent":{"type":["number","null"],"description":"Percent of measured wall time ready to run while waiting for CPU; null without complete same-run readings."},"memoryStallPercent":{"type":["number","null"],"description":"Percent of measured wall time with a thread waiting for memory; null where unmeasured."},"memoryBytes":{"type":"integer","minimum":0,"description":"Average resident memory, bytes."},"memoryPeakBytes":{"type":"integer","minimum":0},"samples":{"type":"integer","minimum":0,"description":"Host readings in the bucket."}},"required":["at","cpuPercent","memoryBytes","samples"],"additionalProperties":true},{"type":"null"}]},"points":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","description":"Start of the bucket, ISO 8601."},"cpuPercent":{"type":["number","null"],"description":"Average CPU, percent of all the sandbox's vCPUs (0-100)."},"cpuCores":{"type":["number","null"],"description":"The same average as a number of cores."},"cpuPeakPercent":{"type":["number","null"],"description":"The busiest interval between two readings in the bucket."},"cpuWaitPercent":{"type":["number","null"],"description":"Percent of measured wall time ready to run while waiting for CPU; null without complete same-run readings."},"memoryStallPercent":{"type":["number","null"],"description":"Percent of measured wall time with a thread waiting for memory; null where unmeasured."},"memoryBytes":{"type":"integer","minimum":0,"description":"Average resident memory, bytes."},"memoryPeakBytes":{"type":"integer","minimum":0},"samples":{"type":"integer","minimum":0,"description":"Host readings in the bucket."}},"required":["at","cpuPercent","memoryBytes","samples"],"additionalProperties":true}}},"required":["sandboxId","range","stepSeconds","points","latest"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/events":{"get":{"operationId":"events.list","summary":"Lifecycle events of your sandboxes, snapshots and volumes, newest first.","description":"What webhooks deliver, to read instead: sandbox.created, sandbox.running, sandbox.paused, sandbox.woken, sandbox.stopped, sandbox.start_failed, sandbox.wake_failed, sandbox.host_unreachable, sandbox.host_reachable, sandbox.recovered, sandbox.recovery_failed, sandbox.files.changed, sandbox.out_of_memory, sandbox.secret_not_applied, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted, volume.recovered, egress_secret.created, egress_secret.updated, egress_secret.deleted, upstream_proxy.set, upstream_proxy.removed, credit.low, credit.empty. Kept 14 days.","tags":["observability"],"parameters":[{"name":"resourceId","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]},"createdAt":{"type":"string"},"resourceId":{"type":["string","null"]},"data":{"type":"object","properties":{},"required":[],"additionalProperties":true,"description":"The resource as it was: data.sandbox, data.snapshot or data.volume; for credit.low and credit.empty, data.credit."}},"required":["id","type","createdAt","data"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks":{"post":{"operationId":"webhooks.create","summary":"Send lifecycle events to a URL.","description":"Returns the webhook with its signing secret, shown this once (and to a retry by the same key with the same Idempotency-Key within 24 hours, until the secret is rotated). Each delivery is a POST of JSON {id, type, createdAt, data} with a Runtime-Signature header, t=<unix seconds>,v1=<hex HMAC-SHA256 of `${t}.${body}` with the secret>; verify it with verifyWebhook in either SDK. Retries back off over about three days (10 attempts); answer 2xx within 10 seconds. At most 16 webhooks an account.","tags":["observability"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"pattern":"^https://","description":"An https URL on the public internet."},"description":{"type":"string","minLength":1,"maxLength":200},"events":{"type":"array","items":{"type":"string","enum":["*","sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]},"minItems":1,"maxItems":32,"description":"Which events to send; [\"*\"], the default, sends every type, including ones added later."}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"webhooks.list","summary":"The account's webhooks, without their secrets.","tags":["observability"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}":{"get":{"operationId":"webhooks.get","summary":"A webhook: where it sends, what, and whether it has been failing.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}:update":{"post":{"operationId":"webhooks.update","summary":"Change a webhook's URL, description or events, or turn it off and on.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"pattern":"^https://","description":"An https URL on the public internet."},"description":{"type":["string","null"],"maxLength":200,"description":"null or empty clears it."},"events":{"type":"array","items":{"type":"string","enum":["*","sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]},"minItems":1,"maxItems":32,"description":"Which events to send; [\"*\"], the default, sends every type, including ones added later."},"enabled":{"type":"boolean","description":"false stops sending and cancels what is waiting."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}:rotate-secret":{"post":{"operationId":"webhooks.rotateSecret","summary":"A new signing secret, shown once. The old one keeps signing beside it for a while.","description":"While both are live every delivery carries two v1 signatures, so a receiver can switch without missing one. keepPreviousSeconds: how long the old secret keeps signing, 0 to 604800 (a week); a day when omitted, 0 to end it at once.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keepPreviousSeconds":{"type":"integer","minimum":0,"maximum":604800}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}:delete":{"post":{"operationId":"webhooks.delete","summary":"Delete a webhook. Nothing more is sent to it.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"secretHint":{"type":"string"},"secret":{"type":"string","description":"The signing secret. Returned when the webhook is made (and to its own retry) and when its secret is rotated, and never again."},"previousSecretExpiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastSuccessAt":{"type":["string","null"]},"lastFailureAt":{"type":["string","null"]},"failingSince":{"type":["string","null"]}},"required":["id","url","events","enabled","secretHint"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}:test":{"post":{"operationId":"webhooks.test","summary":"Send a signed webhook.test event to this webhook now, once.","description":"Answers the delivery once it is settled, waiting up to Prefer: wait=N seconds (10 when omitted): its state, the HTTP status your endpoint answered, the error and how long it took. Works while the webhook is off. Ten a minute.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"resourceId":{"type":["string","null"]},"state":{"type":"string","enum":["pending","succeeded","failed","cancelled"]},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":1},"nextAttemptAt":{"type":["string","null"]},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastDurationMs":{"type":["integer","null"]},"lastAttemptAt":{"type":["string","null"]},"deliveredAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","endpointId","eventId","eventType","state","attempts"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"webhooks.deliveries","summary":"A webhook's deliveries, newest first: each event, its attempts and your endpoint's answers.","description":"Kept 14 days.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"description":"Resource identifier (UUID)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"description":"Page size, 1 to 100."},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","succeeded","failed","cancelled"]}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"resourceId":{"type":["string","null"]},"state":{"type":"string","enum":["pending","succeeded","failed","cancelled"]},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":1},"nextAttemptAt":{"type":["string","null"]},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastDurationMs":{"type":["integer","null"]},"lastAttemptAt":{"type":["string","null"]},"deliveredAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","endpointId","eventId","eventType","state","attempts"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/webhook-deliveries/{id}:retry":{"post":{"operationId":"webhooks.retryDelivery","summary":"Send one delivery again, once, now: a failed one, or one your endpoint lost.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"resourceId":{"type":["string","null"]},"state":{"type":"string","enum":["pending","succeeded","failed","cancelled"]},"attempts":{"type":"integer","minimum":0},"maxAttempts":{"type":"integer","minimum":1},"nextAttemptAt":{"type":["string","null"]},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"lastDurationMs":{"type":["integer","null"]},"lastAttemptAt":{"type":["string","null"]},"deliveredAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","endpointId","eventId","eventType","state","attempts"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/otel-exports":{"post":{"operationId":"otel.create","summary":"Push events as logs and CPU and memory as metrics to an OTLP/HTTP endpoint.","description":"Any OpenTelemetry backend that takes OTLP/HTTP with JSON: an OpenTelemetry Collector, Grafana Cloud, Honeycomb, Datadog, New Relic and others. Events go to <endpoint>/v1/logs as log records; readings to <endpoint>/v1/metrics as the gauges runtime.sandbox.cpu.utilization, runtime.sandbox.cpu.usage, runtime.sandbox.memory.usage and runtime.sandbox.memory.limit, one resource per sandbox. Pushed about every 30 seconds, from the moment the export is made. A failed push is retried, backing off to an hour, and resent from where it stopped while the data is kept. At most 3 an account.","tags":["observability"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","maxLength":2048,"pattern":"^https://","description":"The OTLP/HTTP base URL, as OTEL_EXPORTER_OTLP_ENDPOINT: logs go to <endpoint>/v1/logs and metrics to <endpoint>/v1/metrics."},"headers":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":2048},"maxProperties":10,"description":"Sent with every push, for the endpoint's authentication: Authorization, DD-API-KEY, x-honeycomb-team and so on. Stored where only the sender reads them; never shown again."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]},"minItems":1,"maxItems":2,"description":"What to send: \"logs\" (events as log records) and \"metrics\" (CPU and memory gauges). Both when omitted."}},"required":["endpoint"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"otel.list","summary":"The account's OpenTelemetry exports and how their last push went.","tags":["observability"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}},"nextCursor":{"type":["string","null"],"description":"Pass as cursor; null ends the list."}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/otel-exports/{id}":{"get":{"operationId":"otel.get","summary":"An export: where it pushes, what, when it last succeeded and the last error.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/otel-exports/{id}:update":{"post":{"operationId":"otel.update","summary":"Change an export's endpoint, headers or signals, or turn it off and on.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","maxLength":2048,"pattern":"^https://","description":"The OTLP/HTTP base URL, as OTEL_EXPORTER_OTLP_ENDPOINT: logs go to <endpoint>/v1/logs and metrics to <endpoint>/v1/metrics."},"headers":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":2048},"maxProperties":10,"description":"Replaces every header."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]},"minItems":1,"maxItems":2,"description":"What to send: \"logs\" (events as log records) and \"metrics\" (CPU and memory gauges). Both when omitted."},"enabled":{"type":"boolean","description":"false stops pushing. Turning it back on sends from that moment, not a backlog."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/otel-exports/{id}:flush":{"post":{"operationId":"otel.flush","summary":"Push now rather than at the next interval; read the export after to see the answer.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/otel-exports/{id}:delete":{"post":{"operationId":"otel.delete","summary":"Delete an export and its headers.","tags":["observability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"headerNames":{"type":"array","items":{"type":"string"},"description":"Header names only; values are never shown."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastAttemptAt":{"type":["string","null"]},"lastSuccessAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"failures":{"type":"integer","minimum":0},"exportedEvents":{"type":"integer","minimum":0},"exportedPoints":{"type":"integer","minimum":0}},"required":["id","endpoint","signals","enabled"],"additionalProperties":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/audit":{"get":{"operationId":"audit.list","summary":"The account's audit log, newest first: members, keys, credit, network rules, secrets and deletions, with who, when and from where.","description":"Needs a key for every product or a read-only key, made by an owner or admin. Kept at least 400 days.","tags":["audit"],"parameters":[{"name":"before","in":"query","required":false,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,18}$","description":"A next from the previous page."},"description":"A next from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Page size, 1 to 200."},"description":"Page size, 1 to 200."},{"name":"action","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]+(\\.[a-z_]*)*$","description":"An action (key.created), or a group ending in a dot: member., invitation., key., connection., limit., credit., network., secret., preview., resource., account., sso., scim.."},"description":"An action (key.created), or a group ending in a dot: member., invitation., key., connection., limit., credit., network., secret., preview., resource., account., sso., scim.."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"string","pattern":"^[0-9]+$","description":"Position in the log; page with before."},"id":{"type":"string"},"at":{"type":"string","description":"When, ISO 8601 UTC."},"action":{"type":"string","description":"What happened, like member.role_changed or key.created."},"actor":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent","app","group","runtime"],"description":"runtime: Runtime itself, such as a payment or an expiry."},"id":{"type":["string","null"]},"name":{"type":["string","null"]},"person":{"type":["string","null"],"description":"For an agent: the member whose key it is."}},"required":["kind","id","name","person"],"additionalProperties":false},"target":{"type":"object","properties":{"type":{"type":["string","null"]},"id":{"type":["string","null"]}},"required":["type","id"],"additionalProperties":false},"detail":{"type":"object","additionalProperties":true,"description":"The facts that matter."},"ip":{"type":["string","null"],"description":"The client address the request came from."},"requestId":{"type":["string","null"]},"via":{"type":"string","enum":["web","api","mcp","runtime"]},"sandbox":{"type":["string","null"],"description":"The sandbox the request came from, when code in it called the API at http://runtime.internal."}},"required":["seq","id","at","action","actor","target","detail","ip","requestId","via","sandbox"],"additionalProperties":false}},"next":{"type":["string","null"],"description":"Pass as before for the next, older page; null ends the log."}},"required":["events","next"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sso":{"get":{"operationId":"sso.get","summary":"Single sign-on and directory sync: each identity provider, its domain and whether it is proven, the role people join with, whether SSO is required, and SCIM groups.","description":"Read only; an owner changes single sign-on at withruntime.com/account/single-sign-on. Needs a key for every product or a read-only key, made by an owner or admin.","tags":["sso"],"parameters":[],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":"string","description":"Names the connection in its sign-in URLs."},"protocol":{"type":"string","enum":["oidc","saml"]},"provider":{"type":"string","enum":["okta","entra","google","other"]},"domain":{"type":"string","description":"The email domain it answers for."},"domainVerifiedAt":{"type":["string","null"],"description":"When the domain was proven by DNS; null until then, and until then nobody signs in through it."},"verification":{"type":"object","properties":{"type":{"type":"string","const":"TXT"},"name":{"type":"string"},"value":{"type":"string"}},"required":["type","name","value"],"additionalProperties":false,"description":"The DNS record that proves the domain."},"defaultRole":{"type":"string","enum":["admin","developer","billing"]},"requireSso":{"type":"boolean","description":"Members other than owners may sign in only through it. API keys are unaffected."},"createdAt":{"type":"string"}},"required":["id","providerId","protocol","provider","domain","domainVerifiedAt","verification","defaultRole","requireSso","createdAt"],"additionalProperties":false}},"scim":{"type":"object","properties":{"tokens":{"type":"integer","minimum":0,"description":"Live SCIM tokens."},"users":{"type":"integer","minimum":0,"description":"People the directory has pushed."},"activeUsers":{"type":"integer","minimum":0},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"role":{"type":["string","null"],"description":"The role the group gives, or null."}},"required":["id","displayName","role"],"additionalProperties":false}}},"required":["tokens","users","activeUsers","groups"],"additionalProperties":false},"manage":{"type":"string","description":"Where an owner changes single sign-on."}},"required":["connections","scim","manage"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/sessions":{"post":{"operationId":"sandboxes.sessions.create","summary":"A short-lived token a browser uses to reach this one sandbox directly.","description":"The token runs commands, reads and writes files and reaches previews in this sandbox only, and cannot stop, pause, extend, fork, snapshot or change it, create anything, or reach anything else. It acts as this key's agent and ends when this key is revoked. Lasts ttlSeconds (3600 unless asked, 60 to 86400). Needs a key that may run commands in the sandbox. The token is in this answer only.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ttlSeconds":{"type":"integer","minimum":60,"maximum":86400,"default":3600,"description":"How long it lasts, in seconds: an hour unless asked, a day at most."},"origins":{"type":"array","items":{"type":"string","maxLength":200,"pattern":"^(https://[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*(:[1-9][0-9]{0,4})?|http://(localhost|127\\.0\\.0\\.1|\\[::1\\])(:[1-9][0-9]{0,4})?)$"},"maxItems":10,"description":"The pages that may use it: exact origins, https://host[:port], or http://localhost[:port] while developing. The API answers CORS for these and refuses a request from any other page. Leave empty for a session used only outside a browser."},"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$","description":"Your own handle for it, such as the user it is for."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sandboxId":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"origins":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","description":"The agent whose key made it; the session acts as it."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["active","expired","revoked"]},"token":{"type":["string","null"],"description":"The bearer token, shown once. Null when this answer replays an earlier create with the same Idempotency-Key: revoke that session and make a new one."},"apiUrl":{"type":"string","description":"Where the session is used: this API's origin."}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"get":{"operationId":"sandboxes.sessions.list","summary":"This sandbox's sessions: those still active, and those that ended in the last day.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sandboxId":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"origins":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","description":"The agent whose key made it; the session acts as it."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["active","expired","revoked"]}},"required":[],"additionalProperties":false}},"nextCursor":{"type":"null"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/sandboxes/{id}/sessions/{sessionId}:revoke":{"post":{"operationId":"sandboxes.sessions.revoke","summary":"End a session now. Its next request is refused; revoking one already ended is harmless.","tags":["sandboxes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"},"description":"Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header."}],"responses":{"200":{"description":"Success","headers":{"x-request-id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sandboxId":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"origins":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string","description":"The agent whose key made it; the session acts as it."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["active","expired","revoked"]}},"required":[],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. no_credit_running_limit."},"status":{"type":"integer"},"message":{"type":"string"},"requestId":{"type":"string","description":"Quote this when reporting a problem."},"hint":{"type":"string","description":"What to do next."},"retryAfterMs":{"type":"integer","minimum":0},"details":{"type":"object","description":"Field issues or resume points."}},"required":["code","status","message","requestId","hint"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}},"x-mcp-tools":[{"name":"runtime_sandboxes_create","description":"Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo). The free usage is spent first, then prepaid credit, with nothing to choose. Defaults: 2 vCPU / 4096 MiB / 4096 MiB disk, no time limit: it runs while it works and pauses after 60 idle seconds. Waits up to 60 seconds and returns its state; run commands once it is running. Without credit: 4 running sandboxes at once (a paused one holds no slot), each up to 2 vCPU / 4 GiB, 8 vCPU / 16 GiB in all, at most 10 sandboxes kept and 50 made a day; once the account holds credit, its sandboxes have paid limits and still spend the free usage first.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Your handle for it."},"labels":{"type":"object","description":"Up to 32 key: value tags to filter by."},"env":{"type":"object","description":"Environment variables for every command, terminal and SSH session in it (up to 32). Values are never shown again."},"secrets":{"type":"array","items":{"type":"string"},"description":"The egress secrets it may use, by name (at most 64): only these of the secrets that reach it; [] none; omit for all. Fixed for its life."},"tailscale":{"type":"object","description":"Paid: join your tailnet once running: {authKeySecret (a job secret's name), hostname?, tags?}."},"funding":{"type":"string","enum":["trial","paid"],"description":"Accepted and ignored: free usage first, then credit."},"region":{"type":"string"},"vcpu":{"type":"integer","minimum":1,"maximum":16,"default":2,"description":"At most 16 (2 without credit)."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"default":4096,"description":"At most 65536, 64 GiB (4096 without credit)."},"diskMiB":{"type":"integer","minimum":3072,"maximum":409600,"default":4096,"description":"At least 3072; at most 409600, 400 GiB (10240 without credit)."},"cpu":{"type":"string","enum":["shared","reserved"],"default":"shared"},"cpuFloorMillis":{"type":"integer","minimum":1,"maximum":16000,"description":"Guaranteed CPU, thousandths of a vCPU."},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"default":0,"description":"A time limit, 60 to 86400 s (24 h); 0, the default, is none: it runs while it works."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"default":"pause"},"onLeaseEnd":{"type":"string","enum":["pause","stop","delete"],"description":"onTimeout's older name."},"pausable":{"type":"boolean","deprecated":true,"description":"Ignored since 5 October 2026: every sandbox can pause."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pause after this many idle seconds (no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes). Default 60; 0 never; otherwise 10 to 86400."},"autoWake":{"type":"boolean","default":true,"description":"A request to a paused sandbox wakes it."},"persistent":{"type":"boolean","description":"Paid: never pause it for idleness or a time limit."},"maxTotalCostMicros":{"type":"integer","minimum":1,"description":"The most it may cost over its whole life."},"getOrCreate":{"type":"boolean","description":"With name: return the sandbox holding that name (woken if paused) instead of name_taken."},"maxCostMicros":{"type":"integer","minimum":1,"description":"Deprecated, still accepted: use maxTotalCostMicros."},"network":{"type":"object","description":"Rules from the first start: {internet, allow?, deny?, connect?}, as runtime_sandboxes_network_set."},"image":{"type":"string","description":"Start from this ready image: id, name, name:tag or name@version. Waits for its ready check."},"snapshot":{"type":"string","format":"uuid","description":"Start as a copy of a ready snapshot, on the snapshot's host; not with image. A memory snapshot's copy is its size; a disk snapshot's is the size asked, its disk at least the saved one."},"volumes":{"type":"array","description":"Up to 4 volumes: [{volumeId, path, mode?: rw or snapshot}]."},"wait":{"type":"boolean","default":true},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"additionalProperties":false}},{"name":"runtime_sandboxes_list","description":"List your sandboxes (live ones and stopped ones that keep their disk, unless includeStopped), filtered by state, name or label (key:value), 50 a page; pass nextCursor back as cursor. Give id to read one.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cursor":{"type":"string","description":"Opaque cursor from the previous page's nextCursor."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"state":{"type":"array","items":{"type":"string","enum":["starting","running","pausing","paused","resuming","stopping","stopped"]}},"includeStopped":{"type":"boolean"},"label":{"type":"array","items":{"type":"string"}},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."}},"additionalProperties":false}},{"name":"runtime_sandboxes_manage","description":"stop: end it and its compute charges, keeping its disk (billed as paused storage) for restart. delete: stop it, delete its disk and paused memory, revoke its previews and ports, and remove it from lists for good (its snapshots stay). pause: keep memory and disk, stop compute charges. wake: continue a paused one (seconds: its new time limit, if it has one; no_capacity means retry); a paused one with autoWake also wakes by itself on the next exec, file, terminal or preview request. extend: seconds more for one with a time limit (one without needs none). retention: days (1 to 365) a paused or stopped one is kept; null, the default, keeps it while your account has credit. persist: policy {persistent, maxTotalCostMicros?} keeps it running until stopped, never idle-paused. restart: start a stopped one from its disk. switch-image: move it to image, keeping only /workspace (its home), volumes, env, name and previews; processes restart and everything else on its disk is lost (snapshot first to keep everything); undone if anything fails. update: change name, labels, env (a value sets a variable, null removes it; values are never shown again), autoWake, idlePauseSeconds (0 never; otherwise 10 to 86400, counted from the last activity), timeoutSeconds (a new time limit from now, 60 to 86400, sooner or later than before; 0 removes it) or onTimeout (pause, stop or delete at its end). resize: change vcpu and/or memoryMiB by a restart on its own server; the whole disk stays and every running program stops (a paused one's memory is discarded); no_capacity means its server has no room for the new size, and nothing changed. Waits until done.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["stop","pause","wake","extend","retention","persist","restart","update","delete","switch-image","resize"]},"image":{"type":"string","description":"switch-image: the image to move to: id, name, name:tag or name@version."},"keep":{"type":"string","const":"workspace","description":"switch-image: optional, only \"workspace\", the only thing a switch keeps; older clients send it."},"vcpu":{"type":"integer","minimum":1,"maximum":16,"description":"resize: the new vCPUs, 1 to 16 (without credit 2)."},"memoryMiB":{"type":"integer","minimum":128,"maximum":65536,"description":"resize: the new memory in MiB, 128 to 65536 (without credit 4096)."},"diskMiB":{"type":"integer","minimum":3072,"maximum":409600,"description":"resize: the new disk in MiB, only larger, at most 409600 (without credit 10240); the filesystem grows at the restart."},"restart":{"type":"boolean","const":true,"description":"resize: optional, only true; a resize always restarts. Older clients send it."},"seconds":{"type":"integer","minimum":1,"maximum":86400,"description":"extend: move its time limit this many seconds later. wake: its new time limit, for a sandbox that has one."},"days":{"type":["integer","null"],"minimum":1,"maximum":365,"description":"retention: days to keep a paused sandbox, or null to keep it while your account has credit."},"name":{"type":"string","description":"update: a new name, unique in the account."},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"env":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"update: environment for every later command; a value sets a variable, null removes it."},"autoWake":{"type":"boolean","description":"update: whether a request wakes it when paused."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"update: pause after this many idle seconds, 10 to 86400; 0 never."},"timeoutSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"update: a new time limit from now, 60 to 86400 seconds, sooner or later than before; 0 removes it."},"onTimeout":{"type":"string","enum":["pause","stop","delete"],"description":"update: what its time limit's end does."},"policy":{"type":"object","properties":{"persistent":{"type":"boolean"},"maxTotalCostMicros":{"type":["integer","null"],"minimum":1}},"required":["persistent"],"additionalProperties":false},"wait":{"type":"boolean","default":true,"description":"Wait until the change is done (default)."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_fork","description":"Start count (1 to 100 on prepaid credit, 1 to 8 without credit) running copies of a sandbox, with its files, memory and processes, on its host. Copies keep its size and CPU, and run on the free usage first, then credit. Returns {sandboxes, snapshot}; on an error, details.startedSandboxIds names copies that started. fork_unavailable means forks are switched off; do not retry it.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"count":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"How many copies: 1 to 100 on prepaid credit, 1 to 4 without credit. One fork takes at most a quarter of its server's free memory."},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"secrets":{"type":"array","items":{"type":"string"},"description":"The egress secrets the copies may use: a narrower list than the source's. Omit it and each copy keeps the source's list (every secret that reaches it, when the source names none). A name the source may not use is refused."},"keepSnapshot":{"type":"boolean","default":false,"description":"Keep the snapshot the copies started from, to start more later (it is billed as snapshot storage). By default it is deleted when the fork ends, whether every copy started or not, and nothing is billed for it."},"funding":{"type":"string","enum":["trial","paid"],"description":"Accepted and not read: copies run on what the account's new sandboxes run on, as for a create. On an account without credit, each copy must fit the limits without credit (it has the source's size) and takes one of its running slots."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandboxes_exec","description":"Run a shell command (bash -c) or an argv in a sandbox and get exitCode, stdout and stderr. Output over 16,000 characters in all keeps each stream's first line and its end, with outputCut and a note on reading the rest from a file. Waits for a sandbox that is still starting. A timeout returns timedOut: true with the output so far. background: true returns a processId at once, for servers, watchers and interactive programs; runtime_sandboxes_process reads and controls it. Runs as the sandbox user with passwordless sudo, HOME=/workspace; user root runs it as root instead, with no sudo needed. env sets environment variables and keeps their values out of the command line.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"command":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"A shell command, run as `bash -c \"<command>\"` (pipes, &&, redirection and globs work), or a list of the program and its arguments, run without a shell."},"argv":{"type":"array","items":{"type":"string"},"description":"Or the program and its arguments, run without a shell."},"cwd":{"type":"string","description":"Working directory. Default /workspace."},"env":{"type":"object","additionalProperties":{"type":"string"},"description":"Environment for this command, merged over the sandbox's. Put secrets here, never in the command line: env is never echoed back."},"stdin":{"type":"string","description":"Text given to the command's standard input, which is then closed."},"stdinBase64":{"type":"string","description":"Bytes for standard input, base64."},"user":{"type":"string","enum":["sandbox","root"],"default":"sandbox","description":"Who runs it: the sandbox user (uid 1000, HOME=/workspace), or root, through the sandbox's passwordless sudo with the same environment and PATH and HOME=/root. Saves prefixing every command with sudo."},"timeoutMs":{"type":"integer","minimum":1,"maximum":86400000,"description":"Default 60000. Up to 24 h."},"background":{"type":"boolean","description":"Start it and return at once with a processId."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandboxes_process","description":"Work with a process started by runtime_sandboxes_exec background: true. action read: output after cursor (pass the returned nextCursor next time; waitMs up to 8000 holds the call until there is output), with state and exitCode. write: send input text (the process needs stdinMode pipe or a pty). signal: SIGTERM by default, SIGKILL for the whole tree. list: every running and recent process in the sandbox.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["read","write","signal","list"]},"processId":{"type":"string","description":"Resource identifier."},"cursor":{"type":"integer","minimum":0},"waitMs":{"type":"integer","minimum":0,"maximum":8000},"data":{"type":"string"},"eof":{"type":"boolean"},"signal":{"type":"string","enum":["SIGINT","SIGTERM","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2","SIGKILL"]}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_files_read","description":"Read a file in a sandbox as text (UTF-8) or base64. Text reads can take a line range (startLine, lineCount) so large files come in pieces; the reply says the total line count. At most 1 MiB per read; any path the sandbox user may read.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string","description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"encoding":{"type":"string","enum":["text","base64"],"default":"text"},"startLine":{"type":"integer","minimum":1},"lineCount":{"type":"integer","minimum":1,"maximum":20000}},"required":["id","path"],"additionalProperties":false}},{"name":"runtime_sandboxes_files_write","description":"Create or replace a file in a sandbox, atomically, making parent directories. content is text unless encoding is base64. Up to 1 MiB; for bigger files use the SDK or `npx withruntime sandboxes cp`.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string","description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"content":{"type":"string"},"encoding":{"type":"string","enum":["text","base64"],"default":"text"}},"required":["id","path","content"],"additionalProperties":false}},{"name":"runtime_sandboxes_files_list","description":"List a directory in a sandbox (default /workspace): name, path, type, size, mode, modifiedAt. depth goes deeper (up to 10); glob filters (e.g. **/*.py). At most 2,000 entries; truncated says when there were more.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string","description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"depth":{"type":"integer","minimum":1,"maximum":10},"glob":{"type":"string"},"hidden":{"type":"boolean"},"limit":{"type":"integer","minimum":1,"maximum":2000}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandboxes_files_manage","description":"stat: whether a path exists and what it is. mkdir: make a directory and its parents. rename: move from path to 'to' (overwrite to replace). remove: delete a file or link, or a directory with recursive. Missing paths are not errors for remove and mkdir.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["stat","mkdir","rename","remove"]},"path":{"type":"string","description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"to":{"type":"string","description":"Absolute path in the sandbox, e.g. /workspace/app/main.py. Any path the sandbox user may use."},"recursive":{"type":"boolean"},"overwrite":{"type":"boolean"}},"required":["id","action","path"],"additionalProperties":false}},{"name":"runtime_sandboxes_files_watch","description":"Watch a sandbox file or directory for changes. start (path, recursive, events, include and exclude globs, timeoutMs, webhook: true to have Runtime send the changes to the account's webhooks) returns the watch and a cursor; read (watchId, cursor, waitMs) returns the events since it, repeated writes folded with a count, and nextCursor; list; stop (watchId). Access events are opt-in. At most 4 watches per sandbox; a watch ends after timeoutMs (1 h by default, zero until stopped). Reading never wakes a paused sandbox.","inputSchema":{"type":"object","properties":{"path":{"type":"string"},"recursive":{"type":"boolean","description":"Watch every directory under it too. Default false."},"events":{"type":"array","items":{"type":"string","enum":["create","write","remove","rename","chmod","access"]},"description":"Only these event types. Default: all of create, write, remove, rename, chmod."},"include":{"type":"array","items":{"type":"string"},"description":"Report only paths matching one of these globs, relative to path (`**/*.py`; a bare `*.py` matches at any depth)."},"exclude":{"type":"array","items":{"type":"string"},"description":"Skip paths matching these globs. A directory excluded (`node_modules`, `dist/**`) is not watched at all."},"batchMs":{"type":"integer","minimum":0,"maximum":5000,"description":"Gather events this long and send them as one batch, folding repeated writes to a file into one event with a count. Default 100."},"timeoutMs":{"type":"integer","minimum":0,"maximum":86400000,"description":"The watch ends by itself after running this long; 0 lasts until stopped or the sandbox ends. Default 3600000 (1 h)."},"maxWatches":{"type":"integer","minimum":1,"maximum":50000,"description":"Directories watched at most; past it a `limit` notice. Default 10000."},"id":{"type":"string","format":"uuid"},"webhook":{"type":"boolean","description":"Also send its changes to the account's webhooks as sandbox.files.changed events, read by Runtime without waking the sandbox: at most one event every 2 s a watch, 16 such watches an account. Default false."},"action":{"type":"string","enum":["start","read","list","stop"]},"watchId":{"type":"string","description":"A watch's id."},"cursor":{"type":"integer","minimum":0},"waitMs":{"type":"integer","minimum":0,"maximum":8000},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_interpreter_run","description":"Run code in a stateful interpreter inside a running sandbox: variables and imports persist per context, like notebook cells (Go keeps declarations, not values). Returns stdout, stderr, results (text, HTML, PNG charts, tables for DataFrames) and any error with its traceback; values over 48 KiB come back as refs to files. For data analysis, charts and quick computations; runtime_sandboxes_exec runs shell commands. timeoutMs defaults to 300000.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python by default. R, Java and Go are installed on first use (tens of seconds, once) when the image lacks them."},"context":{"type":"string","description":"A context's id; each language's name is its default context, started on first use."},"timeoutMs":{"type":"integer","minimum":0,"maximum":3600000},"interruptOnDisconnect":{"type":"boolean","default":true},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id","code"],"additionalProperties":false}},{"name":"runtime_sandboxes_interpreter_contexts","description":"List, create, restart, interrupt or remove a sandbox's interpreter contexts, each an isolated interpreter with its own variables. restart clears a context's variables; interrupt stops the running cell and keeps them.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["list","create","restart","interrupt","remove"]},"context":{"type":"string","description":"A context's id; each language's name is its default context, started on first use."},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python by default. R, Java and Go are installed on first use (tens of seconds, once) when the image lacks them."},"env":{"type":"object","additionalProperties":{"type":"string"},"description":"Environment variables for the context's process."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_images_build","description":"Build a sandbox image with your dependencies preinstalled, from exactly one of: `image` (a public or private image such as python:3.12-slim or ghcr.io/you/app:1), `dockerfile` (any Dockerfile: multi-stage, COPY --from, ARG, heredocs; COPY reads `files`), or `recipe` ({base, apt, pip, npm, commands, files, env}). Each build of a `name` is its next version, tagged latest (or `tags`). `start` sets what a sandbox from it runs and when its create answers; a Dockerfile's CMD and HEALTHCHECK fill it in. Returns the image queued; runtime_images action get says when it is ready, and sandboxes start from its id or name:tag. A rebuild reuses unchanged steps.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Your handle for it; each build is its next version."},"tags":{"type":"array","description":"Tags it takes when ready; default latest."},"labels":{"type":"object"},"region":{"type":"string"},"image":{"type":"string","description":"An image, such as python:3.12-slim."},"dockerfile":{"type":"string","description":"A Dockerfile, multi-stage allowed; COPY reads files."},"files":{"type":"array","description":"The Dockerfile's context: [{path, content, encoding?: utf8 or base64, mode?}], 1 MiB in all."},"dockerignore":{"type":"string"},"target":{"type":"string","description":"A stage to build instead of the last."},"buildArgs":{"type":"object"},"recipe":{"type":"object","description":"{base?, apt?, pip?, npm?, commands?, files?, env?, workdir?}: packages and steps on Runtime's base or an image."},"env":{"type":"object","description":"Environment every sandbox from it starts with."},"start":{"type":["object","null"],"description":"{command | argv, cwd?, env?, readyPort? | readyCommand?, readyTimeoutSeconds?}: run as a sandbox starts; its create waits until ready."},"cache":{"type":"boolean","description":"false builds every step afresh."},"build":{"type":"object","description":"{vcpu?, memoryMiB?, diskMiB?, maxImageMiB?, timeoutSeconds?, cacheMiB?} for the build."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"additionalProperties":false}},{"name":"runtime_images_registries","description":"List, store or forget the credentials builds use to pull private images. set: {registry, username, password} (Google: username _json_key, the key as password) or {registry, accessKeyId, secretAccessKey} for Amazon ECR. Never returned.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","set","delete"]},"registry":{"type":"string","description":"The registry host: docker.io, ghcr.io, gcr.io, us-docker.pkg.dev, 123456789012.dkr.ecr.us-east-1.amazonaws.com, or any other."},"username":{"type":"string","description":"Docker Hub or GitHub user, oauth2accesstoken or _json_key for Google."},"password":{"type":"string","description":"A token or password; for _json_key, the service account's JSON key."},"accessKeyId":{"type":"string","description":"Amazon ECR: an AWS access key id."},"secretAccessKey":{"type":"string","description":"Amazon ECR: its secret."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_sandboxes_desktop_record","description":"Record a sandbox's desktop to an MP4 file. start returns the recording id; stop (recordingId) finishes the file at path in the sandbox; list; delete (recordingId). Download it with runtime sandboxes desktop <id> record fetch. One at a time; at most 8192 MiB kept per sandbox; it stops before the disk fills.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["start","stop","list","delete"]},"recordingId":{"type":"string","description":"A recording's id."},"fps":{"type":"integer","minimum":1,"maximum":30,"description":"Frames a second. Default 10."},"maxSeconds":{"type":"integer","minimum":1,"maximum":7200,"description":"Stop after this much video. Default 1800."},"maxMiB":{"type":"integer","minimum":16,"maximum":4096,"description":"The file never grows past this. Default 512."},"crf":{"type":"integer","minimum":18,"maximum":45,"description":"Quality: 18 is sharp and large, 45 small. Default 30."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_desktop_screenshot","description":"A screenshot of a sandbox's desktop, as base64 image data. Needs a started desktop (runtime_sandboxes_desktop_act action start).","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"format":{"type":"string","enum":["png","jpeg"]}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandboxes_desktop_act","description":"Drive a sandbox's Linux desktop like a person: start (width,height) returns a live view URL; move/click/drag/scroll the mouse by pixel coordinates; type text; press keys (xdotool names like ctrl+l, Return); list or focus windows; open a URL in Chromium; launch a program. Take runtime_sandboxes_desktop_screenshot to see the result.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["start","stop","move","click","mouseDown","mouseUp","drag","scroll","type","key","cursor","windows","focus","open","launch","status"]},"x":{"type":"integer","minimum":0,"maximum":16384},"y":{"type":"integer","minimum":0,"maximum":16384},"button":{"type":"string","enum":["left","middle","right"]},"double":{"type":"boolean","description":"click: a double click."},"from":{"type":"array","items":{"type":"integer","minimum":0,"maximum":16384},"description":"drag: [x, y] to press at."},"to":{"type":"array","items":{"type":"integer","minimum":0,"maximum":16384},"description":"drag: [x, y] to release at."},"dy":{"type":"integer","minimum":-100,"maximum":100,"description":"scroll: wheel clicks, positive is down."},"dx":{"type":"integer","minimum":-100,"maximum":100,"description":"scroll: wheel clicks, positive is right."},"text":{"type":"string","description":"type: the text to type."},"delayMs":{"type":"integer","minimum":0,"maximum":200,"description":"type: pause between keystrokes."},"keys":{"type":"string","description":"key: xdotool names, e.g. \"ctrl+l\", \"Return\", \"alt+Tab\"."},"windowId":{"type":"string","description":"focus: an id from the window list."},"url":{"type":"string","description":"open: an http(s) address to open in Chromium."},"argv":{"type":"array","items":{"type":"string"},"description":"launch: a program and its arguments."},"width":{"type":"integer","minimum":320,"maximum":3840},"height":{"type":"integer","minimum":240,"maximum":2160}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_browser","description":"Chromium in a sandbox for browsing agents. start (headless?, width?, height?) returns cdpUrl, a private wss address to give Playwright connectOverCDP, Puppeteer, browser-use or Stagehand; headless false shows it on the sandbox's desktop with a live view. get returns the state and a fresh cdpUrl; stop ends it. A start takes about 1 to 2 seconds: Chromium comes from the host. Only a custom image that is not Ubuntu 24.04 x86_64 installs it on the first start, about a minute. Inside the sandbox it is at http://127.0.0.1:9222.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["start","get","stop"]},"headless":{"type":"boolean","description":"true (the default): no window. false: on the sandbox's desktop, which this starts, with a live view."},"width":{"type":"integer","minimum":240,"maximum":3840,"description":"Window width in pixels. Default 1280."},"height":{"type":"integer","minimum":240,"maximum":2160,"description":"Window height in pixels. Default 800."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandboxes_mcp","description":"Run well-known MCP servers in a sandbox. catalog lists them (GitHub, Postgres, Playwright browser, filesystem, fetch, git, Notion, search...) with their settings and the hosts they call. start returns each one's URL and Authorization header (public: true for URLs that never expire, to configure an agent with once); get shows their state and fresh URLs; stop ends them. Secret settings name Runtime secrets (runtime_secrets), so a server never holds the value, and servers keep to the sandbox's network rules.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Sandbox id. Required for start, get and stop; omit for catalog."},"action":{"type":"string","enum":["catalog","start","get","stop"]},"servers":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"A catalog server's id, from GET /v1/mcp/catalog."},"name":{"type":"string","description":"Its name in the URL (/mcp/<name>). The id by default; required for command."},"secrets":{"type":"object","additionalProperties":{"type":"string"},"description":"A setting the catalog marks secret, to the Runtime secret that fills it: {\"GITHUB_PERSONAL_ACCESS_TOKEN\": \"GITHUB_TOKEN\"}. The server sees only a placeholder; the egress proxy puts the value into its HTTPS requests to the secret's hosts."},"env":{"type":"object","additionalProperties":{"type":"string"},"description":"Plain settings. Proxy variables cannot be set."},"options":{"type":"object","additionalProperties":{"type":"string"}},"command":{"type":"array","items":{"type":"string"},"description":"Instead of id: your own stdio MCP server, a program in the sandbox and its arguments."}}}},"port":{"type":"integer","minimum":1024,"maximum":65535},"replace":{"type":"boolean"},"public":{"type":"boolean"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_switching_record","description":"Record that this organization is switching from a rival. Once per organization, before its first top-up. Credit added within 30 days of signing up is matched, up to $1,000 in total, as each payment settles (a referral, which matches the same payments, applies instead, never both). Call it once the project's real job runs on Runtime: it records the move, it does not make it.","inputSchema":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly","blaxel"]}},"required":["provider"],"additionalProperties":false}},{"name":"runtime_sandboxes_metrics","description":"A sandbox's measured CPU (percent of its vCPUs, and cores), resident memory, CPU wait and memory stalls over a range (15m, 1h, 6h, 24h, 7d, 30d; 1h when omitted), with the latest reading: to size a sandbox, see whether a process is busy or waiting, or find what drove a bill. Waiting is the measured wall-time percentage; null where the host did not provide complete same-run readings.","inputSchema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"range":{"type":"string","enum":["15m","1h","6h","24h","7d","30d"]}},"required":["id"],"additionalProperties":false}},{"name":"runtime_events_list","description":"Recent lifecycle events of your sandboxes, snapshots and volumes, and changes to your egress secrets and upstream proxy, newest first: created, running, paused, woken, stopped, start_failed and the rest, each with the resource as it was (stopReason says why a sandbox stopped). Pass resourceId for one sandbox's history. Kept 14 days.","inputSchema":{"type":"object","properties":{"resourceId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]},"cursor":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."}},"additionalProperties":false}},{"name":"runtime_webhooks_manage","description":"The account's webhooks, which POST signed lifecycle events to an https URL. create returns the signing secret once; keep it. update changes url, events, description or enabled; rotate_secret can keep the old one keepPreviousSeconds; test sends a signed webhook.test and returns your endpoint's answer; deliveries lists recent ones; retry takes a deliveryId. Verify signatures with verifyWebhook from the withruntime SDK.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get","create","update","rotate_secret","delete","test","deliveries","retry"]},"id":{"type":"string","format":"uuid"},"deliveryId":{"type":"string","format":"uuid"},"url":{"type":"string","description":"An https URL on the public internet."},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["*","sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","sandbox.host_unreachable","sandbox.host_reachable","sandbox.recovered","sandbox.recovery_failed","sandbox.files.changed","sandbox.out_of_memory","sandbox.secret_not_applied","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted","volume.recovered","egress_secret.created","egress_secret.updated","egress_secret.deleted","upstream_proxy.set","upstream_proxy.removed","credit.low","credit.empty"]},"description":"Which events to send; [\"*\"], the default, sends every type, including ones added later."},"enabled":{"type":"boolean"},"keepPreviousSeconds":{"type":"integer","minimum":0,"maximum":604800},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_otel_manage","description":"Exports that push sandbox events (OTLP logs) and CPU and memory (OTLP metrics) to an OpenTelemetry endpoint over OTLP/HTTP JSON. create takes endpoint, the OTLP base URL, headers for its authentication and signals (both by default); flush pushes now. Header values are never shown back.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get","create","update","flush","delete"]},"id":{"type":"string","format":"uuid"},"endpoint":{"type":"string","description":"The OTLP/HTTP base URL, as OTEL_EXPORTER_OTLP_ENDPOINT: logs go to <endpoint>/v1/logs and metrics to <endpoint>/v1/metrics."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent with every push, for the endpoint's authentication: Authorization, DD-API-KEY, x-honeycomb-team and so on. Stored where only the sender reads them; never shown again."},"signals":{"type":"array","items":{"type":"string","enum":["logs","metrics"]},"description":"What to send: \"logs\" (events as log records) and \"metrics\" (CPU and memory gauges). Both when omitted."},"enabled":{"type":"boolean"},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_audit_list","description":"The account's audit log, newest first: members, keys, connections, credit, network rules, secrets and deletions, with the time, client address and request id. action filters by an action or a group ending in a dot. Page with before. Needs an owner or admin key.","inputSchema":{"type":"object","properties":{"before":{"type":"string","description":"A next from the previous page."},"limit":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Page size, 1 to 200."},"action":{"type":"string","description":"An action (key.created), or a group ending in a dot: member., invitation., key., connection., limit., credit., network., secret., preview., resource., account., sso., scim.."}},"additionalProperties":false}},{"name":"runtime_ips","description":"Your organization's dedicated outbound addresses, for allow-lists. list: The organization's reserved addresses. reserve(family?): Every sandbox of the organization then sends from its own address; family 4 (default) or 6. Needs credit on the account. release(addressId): Give one back by addressId; sandboxes send from the shared addresses again at once.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","reserve","release"]},"family":{"type":"integer","minimum":4,"maximum":6},"addressId":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_domains","description":"Serve a sandbox port at your own hostname with automatic HTTPS. add(hostname, sandboxId, port): Returns the DNS records to set: a TXT record proving ownership and a CNAME (an A record for an apex). Needs a kept top-up. verify(hostname): Check the TXT record now and activate the domain when it matches; also says whether the name points at Runtime yet. list: Each domain with its state and DNS records. remove(hostname): Stop serving it, open connections included, before this answers; remove its DNS records at your DNS provider too.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["add","verify","list","remove"]},"hostname":{"type":"string"},"sandboxId":{"type":"string","format":"uuid","description":"The sandbox that serves it."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_ports","description":"Public address:port pairs for raw TCP to a sandbox (databases, game servers, anything not HTTP). open(sandboxId, port): Returns the public address:port. Idempotent per sandbox and port. Needs a kept top-up. list(sandboxId?): The open ports, or one sandbox's. close(portId): Close one by portId; its open connections are closed before this answers.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["open","list","close"]},"sandboxId":{"type":"string","format":"uuid","description":"The sandbox that serves it."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."},"portId":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_networks_wireguard","description":"A WireGuard private network from your own network into your sandboxes. create(subnet?): Create it; subnet defaults to 10.250.0.0/16. Needs a kept top-up. get: Its endpoint, gateway key, peers and each sandbox's private address. add_peer(name, publicKey?, routes?): Add a machine or router of yours and get its wg-quick config; without publicKey Runtime generates the pair and the private key is in config, shown once. rotate_peer(peerId, publicKey?): A new key and config; the old key stops working within seconds. remove_peer(peerId): Revoke a peer; its tunnel and connections end within seconds.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["create","get","add_peer","rotate_peer","remove_peer"]},"subnet":{"type":"string"},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"publicKey":{"type":"string","description":"The peer's WireGuard public key. Leave it out and Runtime generates the pair."},"routes":{"type":"array","items":{"type":"string"},"description":"Private IPv4 ranges on your side of this peer that sandboxes may reach, such as 10.0.0.0/16."},"peerId":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_networks_upstream_proxy","description":"Send the organization's sandboxes' outbound connections through your own HTTP or HTTPS proxy. get: The proxy in use, if any. set(url, secret?, hosts?): Needs a kept top-up. A proxy that fails fails the connection; nothing goes around it. remove: Connections leave directly again, within seconds.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set","remove"]},"url":{"type":"string","description":"http://host:port or https://host:port. An https proxy's certificate must verify against the public roots."},"secret":{"type":"string","description":"Optional. One of your secrets, sent as the Proxy-Authorization header's whole value. Its hosts must name the proxy's host."},"hosts":{"type":"array","items":{"type":"string"},"description":"Optional. Only connections to these hosts (or *.domain) go through the proxy; the rest leave as before. Every connection when absent."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_networks_private","description":"Let your sandboxes reach each other at <name>.sandbox.internal over TCP (an account with a kept top-up, free), or stop them. get: On or off, and whether this account may turn it on (it must have a kept top-up). set(enabled): enabled true: each of your sandboxes reaches the others at <name>.sandbox.internal:<port> over TCP. Needs a kept top-up; free. false cuts open connections.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set"]},"enabled":{"type":"boolean","description":"true: your sandboxes reach each other by name. false: they stop, and open connections between them are cut within seconds."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_networks_signed_requests","description":"Let your sandboxes get Runtime's Web Bot Auth signature for outbound HTTP requests (an account with credit, free), or stop them. get: On or off, and whether this account may turn it on (it must have credit). set(enabled): enabled true: a sandbox can get Runtime's Web Bot Auth signature for its outbound HTTP requests, so Cloudflare and other bot managers recognise them as Runtime's agents. Needs credit; free. false stops new signatures at once; ones already given expire within 5 minutes.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set"]},"enabled":{"type":"boolean","description":"true: your sandboxes may get Runtime's request signature. false: new signatures stop at once, and ones already given expire within 5 minutes."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_sandboxes_network","description":"A sandbox's internet access and its allow, deny and connect rules. get(id): The rules, whether the sandbox's host enforces the latest version, and whether host:port reach is open to this organization. set(id, internet, allow?, deny?, connect?): Applies at once, to open connections too. A paid sandbox of an organization with a paid purchase reaches every port and one without credit ports 80 and 443; allow and deny narrow every port, and connect adds host:port pairs. Private addresses are always refused.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","set"]},"id":{"type":"string","format":"uuid"},"internet":{"type":"boolean"},"allow":{"type":"array","items":{"type":"string","description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range."}},"deny":{"type":"array","items":{"type":"string","description":"A domain (example.com), every name under one (*.example.com), an address or a CIDR range."}},"connect":{"type":"array","items":{"type":"string","description":"host:port beyond the web ports, reached as a TCP tunnel through the sandbox's proxy: your own database, a git host over ssh."}}},"required":["action"],"additionalProperties":false}},{"name":"runtime_sandboxes_previews","description":"HTTPS addresses for ports inside a sandbox, https://<port>-<sandbox>.<domain>/. create(id, port, visibility?, ttlSeconds?, expiresAt?, embedOrigins?): private (default) needs the token as the x-runtime-preview-token header, or urlWithToken; public (an account with a kept top-up only) needs none and shows browsers a one-time warning. WebSockets work. embedOrigins limits which sites may show it in an iframe. Idempotent per port. list(id): Each shared port, with a fresh day-long token if private; tokens signed before keep their own expiry. rotate(id, port): A new token; the old ones stop working, as when a link leaked. delete(id, port): Stop sharing the port. session_create(id, sessionSeconds?, origins?): A web page's token for this sandbox's commands, files and previews; shown once. session_list(id): Without tokens. session_revoke(id, sessionId): Ends it now.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["create","list","rotate","delete","session_create","session_list","session_revoke"]},"id":{"type":"string","format":"uuid"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port inside the sandbox."},"visibility":{"type":"string","enum":["private","public"],"description":"private (default): a token is needed. public: anyone with the address; only for an account with a kept top-up."},"ttlSeconds":{"type":"integer","minimum":60,"maximum":604800,"default":86400,"description":"The token's lifetime in seconds."},"expiresAt":{"type":"string","format":"date-time","description":"An absolute private-token deadline, at least a minute and at most a week ahead. The token never outlives it."},"embedOrigins":{"type":["array","null"],"items":{"type":"string"},"description":"The sites that may show this preview in an iframe, as origins: https://app.example.com, https://*.example.com for its subdomains, or http://localhost:3000. Up to 16. Any other site's iframe is refused, and a private link's token works in an iframe only on these. Omitted on a preview that exists: kept as it is. [] or null: any site (the default)."},"sessionSeconds":{"type":"integer","minimum":60,"maximum":86400},"origins":{"type":"array","items":{"type":"string"}},"sessionId":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_sandboxes_mounts","description":"S3, Cloudflare R2 and Google Cloud Storage buckets mounted in a running sandbox. mount(id, provider, bucket, path, prefix?, region?, endpoint?, accountId?, secret?, readOnly?): Mount a bucket at path; secret keeps the key out of the sandbox. list(id): Each mount and whether it is mounted now. unmount(id, path): What was written stays in the bucket.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["mount","list","unmount"]},"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["s3","r2","gcs"],"description":"s3 for Amazon S3 (or any S3-compatible store with endpoint), r2 for Cloudflare R2, gcs for Google Cloud Storage through its S3-compatible XML API with HMAC keys."},"bucket":{"type":"string","description":"The bucket's name."},"path":{"type":"string","description":"Where it appears in the sandbox, such as /data."},"prefix":{"type":"string","description":"Mount only the keys under this prefix."},"region":{"type":"string","description":"The bucket's region; us-east-1 for S3 when omitted."},"endpoint":{"type":"string","description":"An https:// URL for any other S3-compatible store (MinIO, Backblaze B2...)."},"accountId":{"type":"string","description":"For r2: your Cloudflare account id."},"secret":{"type":"string","description":"The name of the secret holding ACCESS_KEY_ID:SECRET_KEY, stored with header Authorization and format \"AWS4-HMAC-SHA256 {value}\" for the endpoint's host. The sandbox never sees the key: the egress proxy signs each request. Omit for a public bucket."},"readOnly":{"type":"boolean","description":"Mount it read-only."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_sandboxes_tailscale","description":"Join a paid sandbox to your Tailscale network with your auth key, see its addresses there, or take it off. up(id, authKeySecret?, hostname?, tags?): Paid sandboxes. authKeySecret names a job secret holding a Tailscale auth key. status(id): Whether it is on one, and its tailnet addresses. down(id): Logs the machine out; it leaves the tailnet at once.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["up","status","down"]},"id":{"type":"string","format":"uuid"},"authKeySecret":{"type":"string","description":"The name of a job secret holding a Tailscale auth key (runtime secrets set NAME --jobs). Use an ephemeral, tagged key; a reusable one lets the sandbox log in again by itself after a long pause."},"hostname":{"type":"string","description":"The machine's name on the tailnet, a DNS label. Default: the sandbox's name, or runtime- and its id's first eight characters."},"tags":{"type":"array","items":{"type":"string"},"description":"Tailscale tags to advertise; the key must be allowed them."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_images","description":"List, read, tag and delete the images sandboxes start from; runtime_images_build makes them. list(cursor?, limit?, state?, name?): Your images, newest first, each as get gives it without the log. name gives that name's versions. Pass nextCursor back as cursor. get(id, logsAfter?): State (queued, building, ready, failed), version, tags, size, error and the last build log lines. tag(id, tag, remove?): Point a tag (prod, v2) at one version, moving it, or take it off with remove: true. delete(id): Delete a version and its tags; sandboxes started from it keep running.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get","tag","delete"]},"cursor":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"state":{"type":"string","enum":["queued","building","ready","failed","deleting"]},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"id":{"type":"string","description":"An image id, a name (its latest tag), name:tag or name@version."},"logsAfter":{"type":"integer","minimum":0,"maximum":1000000},"tag":{"type":"string"},"remove":{"type":"boolean"},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_volumes","description":"Persistent disks that outlive sandboxes, attached at create with volumes: [{volumeId, path}]. create(sizeMiB?, fromBackup?, name?, region?): Give sizeMiB, or fromBackup to restore one. One sandbox at a time mounts it read-write; mode \"snapshot\" gives any number a read-only copy as it is now. It is backed up off its host daily unless turned off; backedUp is true once a checked copy is off the host. list(cursor?, limit?, state?, name?): Your volumes, newest first, each as get gives it. Pass nextCursor back as cursor. get(id): Its state, size, space used, attachments and backups. delete(id): Delete it and all its data; refused while a sandbox holds it. Its backups are kept for their retention.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["create","list","get","delete"]},"sizeMiB":{"type":"integer","minimum":64,"maximum":1048576},"fromBackup":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"region":{"type":"string"},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."},"cursor":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"state":{"type":"string","enum":["creating","ready","failed","deleting"]},"id":{"type":"string","format":"uuid"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_volumes_backup","description":"Crash-consistent backups of a volume, kept off its host. create(volumeId, name?, retentionDays?): Back it up now, kept retentionDays (the volume's retention, 7 unless set); waits up to a minute. Restore with runtime_volumes action create and fromBackup. list(volumeId?, cursor?, limit?, state?): Your backups, newest first, each as get gives it; volumeId gives one volume's. Pass nextCursor back as cursor. get(id): Its state, size, stored bytes and expiry. policy(volumeId, daily?, retentionDays?): Turn daily backups on or off and set how many days each is kept. delete(id): Delete it and its copy off the host.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["create","list","get","policy","delete"]},"volumeId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365; the volume's backup retention (7 unless set) when omitted."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."},"cursor":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"state":{"type":"string","enum":["pending","ready","failed","deleting"]},"id":{"type":"string","format":"uuid"},"daily":{"type":"boolean"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_snapshots","description":"Kept copies of a paused sandbox's files, memory and processes, to start copies from. create(sandboxId, mode?, name?, retentionDays?): Keep a running or paused sandbox, also copied off its host: a running one is paused for the moment it takes and woken again. A sandbox with volumes cannot be snapshotted; an image, not a snapshot, is the way to preinstall dependencies. fork_unavailable means snapshots are switched off; do not retry it. list(cursor?, limit?, state?, name?, sandboxId?): Your snapshots, newest first, each as get gives it; sandboxId gives one sandbox's. Pass nextCursor back as cursor. get(id): Its state, shape, stored bytes and expiry. update(id, name?, labels?, ifLabels?): Replace the supplied labels or change the name; omitted fields stay unchanged. Null clears the name. Captured bytes and billing are unchanged. delete(id): Delete it and free its storage; sandboxes started from it keep running.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["create","list","get","update","delete"]},"sandboxId":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["memory","disk"],"description":"memory (default) saves the whole machine; disk saves files for a fresh boot, without old processes."},"name":{"type":["string","null"],"description":"Your own handle for the resource. Letters, digits, dot, dash, underscore."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365, never past a year from when it was taken. Omit it to keep the snapshot while your account has credit, up to a year from when it was taken (seven days without credit)."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."},"cursor":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."},"state":{"type":"string","enum":["capturing","ready","failed","deleting"]},"id":{"type":"string","format":"uuid"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value tags, at most 32. Filter lists with label=key:value."},"ifLabels":{"type":"object","additionalProperties":{"type":"string"},"description":"Only update if the current complete labels equal these; otherwise snapshot_metadata_changed. Omit for an unconditional update."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_secrets","description":"Secrets such as API keys: sandboxes see a placeholder, and the egress proxy adds the value on HTTPS to the hosts you name. set(name, value, hosts, header?, format?, rules?, only?): Store or replace one. Sandboxes see a placeholder in the environment variable of this name; the egress proxy swaps in the value in a credential header (Authorization, x-api-key and the like) of HTTPS requests to hosts, or sets header on each; never in the URL or another header. rules (an account with credit) limit it by method and path. only limits which sandboxes get it, by label selectors and/or ids. The value is never returned. list: Names, hosts, header and placeholder; never values. delete(name): Erase one by name; its placeholder stops being replaced. It does not revoke the key at its provider.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["set","list","delete"]},"name":{"type":"string","description":"The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores."},"value":{"type":"string","description":"The secret. Visible ASCII and spaces, at most 8 KiB. Stored sealed and never returned."},"hosts":{"type":"array","items":{"type":"string","description":"A host name, or *.domain for every name under it."},"description":"Where the value may go. The proxy puts it only into HTTPS requests to these hosts."},"header":{"type":"string","description":"Optional. Set this header on every request to the hosts, replacing one the sandbox sent, so code needs no placeholder at all; the value then goes into this header and nowhere else. Without it, the placeholder is replaced only in a credential header: Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token."},"format":{"type":"string","description":"Optional, with header. The header's value, with {value} where the secret goes. Default \"{value}\"."},"rules":{"type":"array","items":{"type":"object","properties":{"methods":{"type":"array","items":{"type":"string"},"description":"Optional. The methods allowed; every method when absent."},"paths":{"type":"array","items":{"type":"string"},"description":"Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \\, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :."}},"required":["paths"],"additionalProperties":false},"description":"Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them."},"only":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"},"minProperties":1,"description":"A selector: a sandbox whose labels hold every one of these key/value pairs."},"description":"Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later."},"sandboxes":{"type":"array","items":{"type":"string","format":"uuid"},"description":"These sandboxes (ids of this organization's sandboxes) get the secret."}},"additionalProperties":false,"description":"Optional. Which sandboxes get the secret: those matching labels, and those named in sandboxes. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_account","description":"Read the account. Money is integer microdollars (1,000,000 = $1). get: Who you are (organization, agent, credential) and the account's usage: balance, open holds, free usage left and per-resource charges. limits: Whether this key is read-only; the daily spending limit an owner set on your agent (the limit, what you committed in the last 24 hours and what is left; owners set it at https://withruntime.com/account/keys); and the machine time the account can still run without credit, in milliseconds (free hours given before 5 October 2026: total, used, reserved; available, which counts this month's free usage too), or null with none; and every limit the account is held to with what it uses of each (sandbox.count, sandbox.vcpu, sandbox.memory_mib and the rest), the numbers a create past one is refused quota_exceeded by; and the account's credit: what is left, the days it lasts at this month's pace (state low under 5, empty at none), and who adds more (addedBy agent: no person pays for this account, so add credit yourself with `npx withruntime billing topup <usd>`). referrals: The referral link, the companies that signed up with it and the credit each earned. compare(provider, days?): What this key's sandboxes would have cost at a rival (e2b, daytona, vercel, modal, cloudflare, fly-sprites, fly-machines, blaxel, codesandbox, morph, northflank, runloop, lambda-microvms, freestyle, prime, fly for Sprites): the account's settled usage over the last `days` (default 30), priced at Runtime's rates (what free usage paid for at the standard rates) and at the rival's published list rates, with the date they were checked. Returns the saving, a 30-day projection, a `note` on what was left out, the switch on record and the welcome match's state; with no usage yet, a stated example workload is priced. sso: Identity providers (OIDC or SAML), the email domains they answer for and whether each is proven, the role new people join with, whether SSO is required, and SCIM sync. Needs an owner or admin key; changed on the website. emails: Which of Runtime's optional emails your person gets for this account (own-deletions, billing, usage, tips). Read only: change them with POST /v1/account/emails:update, runtime account emails, or Settings, Emails.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["get","limits","referrals","compare","sso","emails"]},"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly-sprites","fly-machines","blaxel","codesandbox","morph","northflank","runloop","lambda-microvms","freestyle","prime","fly"]},"days":{"type":"integer","minimum":1,"maximum":90}},"required":["action"],"additionalProperties":false}},{"name":"runtime_support","description":"Runtime's support agent, for an error, a sandbox that will not start, billing or a how-to; it can escalate to a person. message(conversationId?, message?, approveActionId?, approveInputHash?, denyActionId?): Start with message; continue with the returned conversationId. While status is working, the reply arrives within about a minute through read. A proposed action runs only when approveActionId is passed with its approveInputHash; denyActionId declines it. read(conversationId): A conversation's status, newest reply and any actions awaiting approval.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["message","read"]},"conversationId":{"type":"string","description":"From a previous reply."},"message":{"type":"string"},"approveActionId":{"type":"string"},"approveInputHash":{"type":"string"},"denyActionId":{"type":"string"}},"required":["action"],"additionalProperties":false}},{"name":"runtime_feedback","description":"Reports go straight to the Runtime team, and whoever asked is told when a fix ships. submit(kind, summary, detail?, competitor?, resourceId?, requestId?, context?): A bug, a limit or missing feature, a workaround, unclear docs, something slow, or something another provider does better; praise too. Give what was tried, what happened and the requestId, never credentials, private files or user data. Duplicates merge. list(limit?): This organization's reports, newest first, with the status (new, planned, shipped, declined) and ship note of the item each merged into; one not yet sorted is waiting to be sorted, which runs every hour.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["submit","list"]},"kind":{"type":"string","enum":["bug","missing_feature","competitor_gap","migration_blocker","docs","pricing","praise","other"],"description":"bug | missing_feature | competitor_gap (something another provider does better) | migration_blocker (what stops a move to Runtime) | docs | pricing | praise | other"},"summary":{"type":"string","description":"One line."},"detail":{"type":"string","description":"What happened, what you expected, how to reproduce."},"competitor":{"type":"string","description":"E.g. E2B, Daytona, Modal, Vercel Sandbox."},"resourceId":{"type":"string","format":"uuid"},"requestId":{"type":"string","description":"From the error you are reporting."},"context":{"type":"object","description":"Anything else useful, at most 4 KB of JSON."},"idempotencyKey":{"type":"string","description":"Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error."},"limit":{"type":"integer","minimum":1,"maximum":500}},"required":["action"],"additionalProperties":false}}]}