{"openapi":"3.1.0","info":{"title":"Runtime Cloud API","version":"0.2.0","description":"One API for every Runtime Cloud product. Bearer key auth, 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"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. trial_busy."},"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."}},"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. trial_busy."},"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, trial time and per-resource charges, in integer microdollars.","tags":["account"],"parameters":[],"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":"The free trial in milliseconds, or null when the account has none.","properties":{"totalMs":{"type":"integer","minimum":0},"usedMs":{"type":"integer","minimum":0},"reservedMs":{"type":"integer","minimum":0},"availableMs":{"type":"integer","minimum":0}}},"resources":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"This principal's hundred newest resources and what each has used and been charged."}},"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. trial_busy."},"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 trial when the account has trial time, the default region and a 2 vCPU / 4096 MiB / 4096 MiB machine that starts from a warm template. 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 returns the first result and never repeats the effect. 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."},"funding":{"type":"string","enum":["trial","paid"],"description":"Omit to use the free trial when the account has trial time left, and prepaid credit only once the trial is used up. A trial request never falls back to credit."},"region":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,31}$","description":"Omit for the default region."},"vcpu":{"type":"integer","minimum":1,"maximum":128,"default":2},"memoryMiB":{"type":"integer","minimum":128,"maximum":1048576,"default":4096},"diskMiB":{"type":"integer","minimum":3072,"maximum":16777216,"default":4096},"cpu":{"type":"string","enum":["shared","reserved"],"default":"shared"},"cpuFloorMillis":{"type":"integer","minimum":1,"maximum":128000,"default":50,"description":"Guaranteed CPU in thousandths of a vCPU while shared. Reserved CPU guarantees all of it."},"timeoutSeconds":{"type":"integer","minimum":60,"maximum":3600,"default":1800,"description":"How long the sandbox may run before its lease ends. A trial is capped at its remaining time."},"pausable":{"type":"boolean","default":true,"description":"Allow pause and wake. Default true."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pause the sandbox after this many seconds with no exec, file, process, terminal, desktop or preview request; nothing is lost, and with autoWake the next request wakes it. 0 is never; otherwise 60 to 86400. When left out: 300 for a sandbox whose timeoutSeconds is left out, counted only until its first use; never when timeoutSeconds is given or the sandbox starts from an image or a snapshot."},"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 running while credit lasts: the lease renews itself, and after a stop the disk is kept (billed as reserved disk) so :restart starts it again. Paid only."},"maxTotalCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"The most this sandbox may cost over its whole life, in microdollars; renewals stop 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 if stopped and persistent. The other fields apply only when it is created."},"onLeaseEnd":{"type":"string","enum":["pause","stop"],"default":"pause","description":"What happens when timeoutSeconds runs out: pause (keep memory and files; wake later) or stop. Default pause."},"maxCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"Refuse the create if the quote for its first lease exceeds this."},"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. Trial sandboxes 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,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","description":"Start from this ready image: its id, name (its latest tag), name:tag or name@version (POST /v1/images, runtime image 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): its files, memory and running processes, on the host that keeps it. The copy gets the snapshot's vCPUs, memory and disk. Not with image."},"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."}},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 stopped sandboxes (default false)."},"description":"Include stopped sandboxes (default false)."},{"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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. timeoutSeconds sets the new lease; the default is the sandbox's own timeout, and a trial is capped at its time left.","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 returns the first result and never repeats the effect. 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":3600}},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 running sandbox more time: its lease moves this many seconds later.","description":"Never more than an hour ahead of now. Paid time is funded first; a trial extends only within its time left.","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 returns the first result and never repeats the effect. 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":3600}},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 sandbox is kept (1 to 365 days) before it is deleted.","description":"Counts from the current pause. Paused storage is billed at its quoted rate; a trial keeps its free seven days. Low credit can shorten it, 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 returns the first result and never repeats the effect. 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","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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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, persistent sandbox again from its 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 returns the first result and never repeats the effect. 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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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, automatic wake, idle pause or persistence. Fields left out stay as they are.","description":"idlePauseSeconds set here counts from the last exec, file, terminal, desktop or preview request; 0 turns idle pause off. persistent: true keeps the sandbox running while credit lasts (its lease renews itself) and keeps its disk after a stop, billed as reserved disk; paid sandboxes 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 returns the first result and never repeats the effect. 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."},"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 exec, file, process, terminal, desktop or preview request, counted from now. 0 is never; otherwise 60 to 86400."},"persistent":{"type":"boolean","description":"Keep running while credit lasts: the lease renews itself, and after a stop the disk is kept (billed as reserved disk) for :restart. 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."}},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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":10,"default":1,"description":"How many copies, 1 to 10."},"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."},"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":"What the copies run on, as for a create: \"trial\" or \"paid\" (prepaid credit). Omit to use the source sandbox's funding. A trial fork must fit the trial: each copy has the source's size, and every copy takes one of the trial's running slots. A trial request never falls back to credit."}},"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"]},"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"},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pauses after this many idle seconds; 0 is never."},"idlePauseUnusedOnly":{"type":"boolean","description":"True for the default idle pause, which pauses only a sandbox nothing has used yet. 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":"Its disk is kept after a stop (restart it with :restart) and its lease renews itself while credit lasts."},"lastActiveAt":{"type":["string","null"],"format":"date-time","description":"The last exec, file, terminal, desktop or preview request, to within a minute."},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"When the sandbox's lease ends."},"endedAt":{"type":["string","null"],"format":"date-time"},"stopReason":{"type":["string","null"],"description":"Why it stopped or paused, for example requested, lease_expired, idle, insufficient_funds (credit ran out), lifetime_cap (this sandbox's own maxTotalCostMicros), or spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits)."},"pausedAt":{"type":["string","null"]},"pausedExpiresAt":{"type":["string","null"]},"memoryRestored":{"type":"boolean"},"chargedMicros":{"type":"integer","minimum":0,"description":"Settled, in microdollars (1,000,000 = $1)."},"heldMicros":{"type":"integer","minimum":0,"description":"Reserved against open intervals."},"rates":{"type":"object"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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."},"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"}},"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."},"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."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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."},"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"},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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"},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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."},"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."},"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. trial_busy."},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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"},"cwd":{"type":"string"},"pty":{"type":"boolean"},"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"}},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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"}},"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. trial_busy."},"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"}},"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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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 directory for file 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). Events are create, write, remove, rename (with oldPath) and chmod, 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. 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 returns the first result and never repeats the effect. 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"]},"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":1000,"maximum":86400000,"description":"The watch ends by itself after running this long. 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."}},"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."}},"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. trial_busy."},"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."}},"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. trial_busy."},"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"]},"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. trial_busy."},"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, and the watch ends by its own timeout.","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 returns the first result and never repeats the effect. 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. trial_busy."},"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.","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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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 (default), javascript, typescript, r, java, bash or go. R, Java and Go are installed in the sandbox on first use (tens of seconds, once) when its image lacks them."},"context":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id. Each language's name (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's default context, started on first use."},"timeoutMs":{"type":"integer","minimum":1,"maximum":3600000,"default":300000,"description":"Interrupt the cell after this long. 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."}},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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 (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's default context, started on first use."},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python (default), javascript, typescript, r, java, bash or go. R, Java and Go are installed in the sandbox on first use (tens of seconds, once) when its 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. trial_busy."},"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 (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's 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 returns the first result and never repeats the effect. 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. trial_busy."},"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 (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's 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 returns the first result and never repeats the effect. 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. trial_busy."},"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 (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's 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 returns the first result and never repeats the effect. 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. trial_busy."},"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 (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's 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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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 has bought credit, then four. An identical plan in the same organization 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 returns the first result and never repeats the effect. 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."},"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":1024,"maximum":32768,"default":4096,"description":"The build guest's own scratch disk: earlier stages and the context live here."},"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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"sizeMiB":{"type":["integer","null"]},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"createdAt":{"type":"string"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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."}},"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. trial_busy."},"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"]},"createdAt":{"type":"string"},"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. trial_busy."},"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"]},"createdAt":{"type":"string"},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"]},"createdAt":{"type":"string"},"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. trial_busy."},"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 paused sandbox, to start new sandboxes from.","description":"The sandbox must be paused (create it with pausable: true, then pause it). Ready in well under a second; send Prefer: wait=10 to wait for it. The sandbox is untouched and can be resumed at once. Start copies with POST /v1/sandboxes and snapshot: <id>. Every sandbox started from a snapshot continues 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. A snapshot lives on its source sandbox's host, and sandboxes started from it run on that host. It is also copied off the host, 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 returns the first result and never repeats the effect. 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; 7 when omitted. Never past a year from when it was taken."}},"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"},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the bytes this snapshot alone stores."},"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: a fork's own snapshot, never copied. 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"}},"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. trial_busy."},"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"},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the bytes this snapshot alone stores."},"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: a fork's own snapshot, never copied. 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"}},"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. trial_busy."},"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"},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the bytes this snapshot alone stores."},"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: a fork's own snapshot, never copied. 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"}},"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. trial_busy."},"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.","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 returns the first result and never repeats the effect. 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","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365; 7 when omitted. Never past 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"},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the bytes this snapshot alone stores."},"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: a fork's own snapshot, never copied. 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"}},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"},"status":{"type":"string"},"state":{"type":"string","enum":["capturing","ready","failed","deleting","deleted"]},"name":{"type":["string","null"]},"sourceSandboxId":{"type":"string"},"shape":{"type":"object","properties":{"vcpu":{"type":"integer"},"memoryMiB":{"type":"integer"},"diskMiB":{"type":"integer"},"memoryGuarantee":{"type":"string"}},"required":[],"additionalProperties":false},"retentionDays":{"type":"integer"},"storedBytes":{"type":["integer","null"]},"meteredBytes":{"type":["integer","null"],"description":"What storage is metered for: the bytes this snapshot alone stores."},"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: a fork's own snapshot, never copied. 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"}},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 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.","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 returns the first result and never repeats the effect. 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 your server listens on inside the sandbox."},"visibility":{"type":"string","enum":["private","public"],"description":"private (default): a token is needed. public: anyone with the address."},"ttlSeconds":{"type":"integer","minimum":60,"maximum":604800,"default":86400,"description":"How long the token lasts, in seconds. One day unless asked; a week at most."}},"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 fresh signed token."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time"},"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."},"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. trial_busy."},"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.","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 fresh signed token."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time"},"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."},"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. trial_busy."},"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":"How long the token lasts, in seconds. One day unless asked; a week at most."},"description":"How long the token lasts, in seconds. One day unless asked; a week at most."}],"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 fresh signed token."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time"},"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."},"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. trial_busy."},"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. Open connections close within seconds.","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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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 fresh signed token."},"tokenExpiresAt":{"type":["string","null"],"format":"date-time"},"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."},"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. trial_busy."},"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 trial sandbox 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. trial_busy."},"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 trial sandbox 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 returns the first result and never repeats the effect. 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. Trial sandboxes 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 trial sandbox 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. trial_busy."},"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 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. Paid accounts only. Calling it again with another sandbox or port points the name there.","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 returns the first result and never repeats the effect. 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 that serves it."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."}},"required":["hostname","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"},"hostname":{"type":"string"},"sandboxId":{"type":"string"},"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"]},"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. trial_busy."},"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"},"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"]},"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. trial_busy."},"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"},"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"]},"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. trial_busy."},"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. 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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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"},"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"]},"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. trial_busy."},"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. Paid accounts only; 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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. Open connections end within seconds.","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 returns the first result and never repeats the effect. 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. trial_busy."},"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/addresses":{"post":{"operationId":"addresses.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. Paid accounts only.","tags":["addresses"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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":"addresses.list","summary":"Your dedicated outbound addresses.","tags":["addresses"],"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. trial_busy."},"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/addresses/{id}":{"delete":{"operationId":"addresses.release","summary":"Release a dedicated address. Sandboxes go back to the shared addresses at once.","tags":["addresses"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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/tunnel":{"get":{"operationId":"tunnel.get","summary":"Your private network: its WireGuard endpoint, peers, and each sandbox's address in it.","tags":["tunnel"],"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. trial_busy."},"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":"tunnel.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. Paid accounts only. Calling it again returns the network you have.","tags":["tunnel"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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":"tunnel.delete","summary":"Delete your private network and every peer. Tunnels close within seconds.","tags":["tunnel"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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/tunnel/peers":{"post":{"operationId":"tunnel.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":["tunnel"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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/tunnel/peers/{id}:rotate":{"post":{"operationId":"tunnel.peers.rotate","summary":"Give a peer a new key. The old key stops working within seconds.","tags":["tunnel"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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/tunnel/peers/{id}":{"delete":{"operationId":"tunnel.peers.remove","summary":"Remove a peer. Its tunnel and connections end within seconds.","tags":["tunnel"],"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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 Firefox."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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."}},"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"]},"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."},"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. trial_busy."},"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"]},"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."},"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. trial_busy."},"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.","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 returns the first result and never repeats the effect. 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. trial_busy."},"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":"When a company that signed up with your link makes its first top-up of at least $10, you and it each get credit equal to that top-up: at least $25 and at most $500 each, up to $10,000 a calendar year for you. 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: a first top-up is matched, but never below this. Integer microdollars, as a string."},"maxRewardMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most each side gets: a first top-up is matched up to this. Integer microdollars, as a string."},"minPurchaseMicros":{"type":"string","pattern":"^[0-9]+$","description":"The smallest first top-up that pays a referral. Integer microdollars, as a string."},"yearlyCapMicros":{"type":"string","pattern":"^[0-9]+$","description":"The most referral credit 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 top-up not made yet."},"paid":{"type":"integer","minimum":0,"description":"First top-up made: both sides credited."},"capped":{"type":"integer","minimum":0,"description":"Paid, but the yearly cap left you less than the matched reward."},"reversed":{"type":"integer","minimum":0,"description":"The qualifying top-up was refunded or disputed below $10, so both rewards were taken back."},"earnedMicros":{"type":"string","pattern":"^[0-9]+$","description":"Referral credit you kept, all time. 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."},"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"],"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. trial_busy."},"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 trial sandbox at the standard rates, since the trial charges 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`). Compute only: storage, network, plan fees and free allowances are left out. Also returns the switching credit'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","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","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 the free trial paid for. The trial charged nothing for them; runtimeMicros prices them at Runtime's standard rates."},"trialRunSeconds":{"type":"number","minimum":0,"description":"The running time the free trial 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 trial sandbox at the standard rates, not the trial's 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 a first top-up is matched to. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly"]}},"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"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: waiting for the first top-up. paid: matched. superseded: a referral matched the top-up instead, which is never less. refused: see refusedReason. reversed: the top-up was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The switching credit this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}}},"required":["enabled","maxMicros","providers","eligible","switch"],"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. trial_busy."},"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 switching credit: whether you can still record a switch, and what it paid.","description":"An organization switching from a rival gets its first top-up matched, up to $100, once the payment has settled. Record the switch 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 a first top-up is matched to. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly"]}},"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"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: waiting for the first top-up. paid: matched. superseded: a referral matched the top-up instead, which is never less. refused: see refusedReason. reversed: the top-up was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The switching credit this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}}},"required":["enabled","maxMicros","providers","eligible","switch"],"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. trial_busy."},"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. The first top-up is then matched, up to $100, as credit once the payment settles; a referral that matches the same top-up applies instead, never both. A refund or chargeback of the top-up takes the match back. 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 returns the first result and never repeats the effect. 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"]}},"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 a first top-up is matched to. Integer microdollars, as a string (1,000,000 = $1)."},"providers":{"type":"array","items":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly"]}},"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"]},"status":{"type":"string","enum":["pending","paid","superseded","refused","reversed"],"description":"pending: waiting for the first top-up. paid: matched. superseded: a referral matched the top-up instead, which is never less. refused: see refusedReason. reversed: the top-up was refunded or disputed."},"refusedReason":{"type":["string","null"],"enum":["program_off","suspended","same_card","fraud",null]},"recordedAt":{"type":"string","format":"date-time"},"creditMicros":{"type":"string","pattern":"^[0-9]+$","description":"The switching credit this organization got and kept. Integer microdollars, as a string (1,000,000 = $1)."}}}},"required":["enabled","maxMicros","providers","eligible","switch"],"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. trial_busy."},"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, and its agent's daily spending limit with what is left.","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). 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}},"required":["access","daily"],"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. trial_busy."},"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"},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. The proxy replaces it with the value in the request line and headers of HTTPS requests to the hosts."},"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. trial_busy."},"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 gets an environment variable of this name holding a placeholder. The egress proxy replaces the placeholder with the value in the request line and headers of HTTPS requests to the hosts, and with header set it sets that header on every such request. 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 returns the first result and never repeats the effect. 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.","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}"]}},"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"},"placeholder":{"type":"string","description":"What the sandbox sees in the environment variable. The proxy replaces it with the value in the request line and headers of HTTPS requests to the hosts."},"valueBytes":{"type":"integer","minimum":1,"maximum":8192},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"enforced":{"type":"boolean"}},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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"}},"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. trial_busy."},"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 and memory 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."},"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."},"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. trial_busy."},"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, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted. 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","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]}},{"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","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]},"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."}},"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. trial_busy."},"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 with the same Idempotency-Key). 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 returns the first result and never repeats the effect. 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","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]},"minItems":1,"maxItems":32,"description":"Which events to send: any of sandbox.created, sandbox.running, sandbox.paused, sandbox.woken, sandbox.stopped, sandbox.start_failed, sandbox.wake_failed, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted; or [\"*\"] for every type, including ones added later (the default)."}},"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 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. trial_busy."},"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 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. trial_busy."},"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 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. trial_busy."},"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 returns the first result and never repeats the effect. 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","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]},"minItems":1,"maxItems":32,"description":"Which events to send: any of sandbox.created, sandbox.running, sandbox.paused, sandbox.woken, sandbox.stopped, sandbox.start_failed, sandbox.wake_failed, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted; or [\"*\"] for every type, including ones added later (the default)."},"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 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. trial_busy."},"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 returns the first result and never repeats the effect. 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 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. trial_busy."},"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 returns the first result and never repeats the effect. 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 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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. trial_busy."},"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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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 returns the first result and never repeats the effect. 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. trial_busy."},"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"]}},"required":["seq","id","at","action","actor","target","detail","ip","requestId","via"],"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. trial_busy."},"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. trial_busy."},"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_account_get","description":"Read who you are (organization, agent, credential) and the account's usage: prepaid balance, open holds, free-trial time left and per-resource charges, all in integer microdollars (1,000,000 = $1). Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_sandbox_create","description":"Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo). Use funding \"trial\" for a free first run; omitted funding can use paid credit after the trial. Defaults: 2 vCPU / 4096 MiB / 4096 MiB disk for 30 minutes. Waits up to 60 seconds: inspect the returned state and use runtime_sandbox_exec only when running. Check command exitCode, timedOut and output, then stop with runtime_sandbox_manage and confirm stopped. Trial: 50 free hours, 8 running sandboxes at once (a paused one holds no slot), each up to 2 vCPU / 4 GiB.","inputSchema":{"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."},"funding":{"type":"string","enum":["trial","paid"],"description":"Omit to use the free trial when the account has trial time left, and prepaid credit only once the trial is used up. A trial request never falls back to credit."},"region":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,31}$","description":"Omit for the default region."},"vcpu":{"type":"integer","minimum":1,"maximum":128,"default":2},"memoryMiB":{"type":"integer","minimum":128,"maximum":1048576,"default":4096},"diskMiB":{"type":"integer","minimum":3072,"maximum":16777216,"default":4096},"cpu":{"type":"string","enum":["shared","reserved"],"default":"shared"},"cpuFloorMillis":{"type":"integer","minimum":1,"maximum":128000,"default":50,"description":"Guaranteed CPU in thousandths of a vCPU while shared. Reserved CPU guarantees all of it."},"timeoutSeconds":{"type":"integer","minimum":60,"maximum":3600,"default":1800,"description":"How long the sandbox may run before its lease ends. A trial is capped at its remaining time."},"pausable":{"type":"boolean","default":true,"description":"Allow pause and wake. Default true."},"idlePauseSeconds":{"type":"integer","minimum":0,"maximum":86400,"description":"Pause the sandbox after this many seconds with no exec, file, process, terminal, desktop or preview request; nothing is lost, and with autoWake the next request wakes it. 0 is never; otherwise 60 to 86400. When left out: 300 for a sandbox whose timeoutSeconds is left out, counted only until its first use; never when timeoutSeconds is given or the sandbox starts from an image or a snapshot."},"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 running while credit lasts: the lease renews itself, and after a stop the disk is kept (billed as reserved disk) so :restart starts it again. Paid only."},"maxTotalCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"The most this sandbox may cost over its whole life, in microdollars; renewals stop 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 if stopped and persistent. The other fields apply only when it is created."},"onLeaseEnd":{"type":"string","enum":["pause","stop"],"default":"pause","description":"What happens when timeoutSeconds runs out: pause (keep memory and files; wake later) or stop. Default pause."},"maxCostMicros":{"type":"integer","minimum":1,"maximum":1000000000000,"description":"Refuse the create if the quote for its first lease exceeds this."},"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. Trial sandboxes 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,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","description":"Start from this ready image: its id, name (its latest tag), name:tag or name@version (POST /v1/images, runtime image 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): its files, memory and running processes, on the host that keeps it. The copy gets the snapshot's vCPUs, memory and disk. Not with image."},"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."},"wait":{"type":"boolean","default":true,"description":"Wait until it is running (default)."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Choose a unique key before the first write; reuse it with identical input after a lost reply. New action, new key."}},"required":[],"additionalProperties":false}},{"name":"runtime_sandbox_list","description":"List your sandboxes (live ones unless includeStopped), filtered by state, name or label (key:value), up to 50 a page; pass nextCursor back as cursor for more. Give id to read one sandbox instead.","inputSchema":{"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)."},"cursor":{"type":"string","maxLength":512,"pattern":"^[A-Za-z0-9_-]+$","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","maxLength":300}},"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."}},"required":[],"additionalProperties":false}},{"name":"runtime_sandbox_manage","description":"stop: end it and its compute charges (do this when done). pause: keep memory and disk, stop compute charges. wake: continue a paused one (seconds: its new lease; 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. retention: days (1 to 365) a paused one is kept. persist: policy {persistent, maxTotalCostMicros?} keeps it running while credit lasts and keeps its disk after a stop. restart: start a stopped persistent one from its disk. update: change name, labels, autoWake or idlePauseSeconds (0 never; otherwise counted from the last activity). Waits until done.","inputSchema":{"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)."},"action":{"type":"string","enum":["stop","pause","wake","extend","retention","persist","restart","update"]},"seconds":{"type":"integer","minimum":1,"maximum":3600,"description":"extend: move the lease this many seconds later. wake: the new lease."},"days":{"type":"integer","minimum":1,"maximum":365,"description":"retention: days to keep a paused sandbox."},"name":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$","description":"update: a new name, unique in the account."},"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."},"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; 0 never."},"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","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Choose a unique key before the first write; reuse it with identical input after a lost reply. New action, new key."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandbox_fork","description":"Start count (1 to 10) copies of a sandbox's files, memory and running processes, on the source's host. funding means what it means for a create; left out, copies keep the source's funding. Copies keep the source's size and CPU. Returns {sandboxes, snapshot}; check each copy's state before using it. On an error, details.startedSandboxIds names copies that did start; stop them if unwanted. To install dependencies once for sandboxes on any host, build an image with runtime_image_build instead. fork_unavailable means an operator has switched forks off; it is not retryable.","inputSchema":{"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)."},"count":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"How many copies, 1 to 10."},"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."},"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":"What the copies run on, as for a create: \"trial\" or \"paid\" (prepaid credit). Omit to use the source sandbox's funding. A trial fork must fit the trial: each copy has the source's size, and every copy takes one of the trial's running slots. A trial request never falls back to credit."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Choose a unique key before the first write; reuse it with identical input after a lost reply. New action, new key."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_exec","description":"Run a shell command (bash -c) or an argv in a sandbox and get exitCode, stdout and stderr (first 64 KiB of each for commands up to 60 s; 1 MiB for longer ones). Waits for a sandbox that is still starting. A timeout returns timedOut: true with the output so far. For servers, watchers or anything interactive set background: true: it returns a processId at once; follow it with runtime_sandbox_process. Runs as the sandbox user with passwordless sudo, HOME=/workspace. Pass secrets in env, never in the command.","inputSchema":{"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)."},"command":{"oneOf":[{"type":"string","minLength":1,"maxLength":16384,"description":"A shell command, run as `bash -c \"<command>\"`: pipes, &&, redirection and globs work."},{"type":"array","items":{"type":"string","maxLength":16384},"minItems":1,"maxItems":128,"description":"Or the program and its arguments, run without a shell."}],"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","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."},"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","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Optional. Reuse the same value only when retrying after a lost reply: the command then never runs twice."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_process","description":"Work with a process started by runtime_sandbox_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","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)."},"action":{"type":"string","enum":["read","write","signal","list"]},"processId":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."},"cursor":{"type":"integer","minimum":0},"waitMs":{"type":"integer","minimum":0,"maximum":8000},"data":{"type":"string","maxLength":1048576},"eof":{"type":"boolean"},"signal":{"type":"string","enum":["SIGINT","SIGTERM","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2","SIGKILL"]}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_sandbox_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","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","minLength":1,"maxLength":4096,"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_sandbox_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 sandbox cp`.","inputSchema":{"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)."},"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."},"content":{"type":"string","maxLength":1400000},"encoding":{"type":"string","enum":["text","base64"],"default":"text"}},"required":["id","path","content"],"additionalProperties":false}},{"name":"runtime_sandbox_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","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","minLength":1,"maxLength":4096,"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","maxLength":512},"hidden":{"type":"boolean"},"limit":{"type":"integer","minimum":1,"maximum":2000}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_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","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)."},"action":{"type":"string","enum":["stat","mkdir","rename","remove"]},"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."},"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."},"recursive":{"type":"boolean"},"overwrite":{"type":"boolean"}},"required":["id","action","path"],"additionalProperties":false}},{"name":"runtime_sandbox_files_watch","description":"Watch a sandbox directory for file changes. id is the sandbox. action=start (path, recursive, events, include, exclude globs, timeoutMs; watchId to name it) returns the watch and a cursor. action=read (watchId, cursor, waitMs up to 8000) returns the events since the cursor (create, write, remove, rename, chmod; repeated writes folded with a count) and nextCursor to pass next time. action=list, action=stop (watchId). At most 4 watches per sandbox; a watch ends after timeoutMs (1 h by default). Reading never wakes a paused sandbox.","inputSchema":{"type":"object","properties":{"path":{"type":"string","maxLength":4096},"recursive":{"type":"boolean","description":"Watch every directory under it too. Default false."},"events":{"type":"array","items":{"type":"string","enum":["create","write","remove","rename","chmod"]},"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":1000,"maximum":86400000,"description":"The watch ends by itself after running this long. 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-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$","description":"Resource identifier (UUID)."},"action":{"type":"string","enum":["start","read","list","stop"]},"watchId":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,39}$","description":"A watch's id."},"cursor":{"type":"integer","minimum":0},"waitMs":{"type":"integer","minimum":0,"maximum":8000},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_feedback_submit","description":"Please tell us what could be better: this goes straight to the Runtime team and into what we fix next. Whenever something gets in your way, send it as it happens, without waiting to be asked: an error that looks like ours, a limit or missing feature, a workaround you needed, unclear docs, something slower or harder than it should be, or something another provider (E2B, Daytona, Modal, Vercel, Cloudflare, Fly...) does better. Praise is welcome too. Small things count. Include what you tried, what happened and the requestId, but never credentials, private files or user data, and let the user know in one line what you reported. Duplicates merge; it is sorted into an item within the hourly triage, and runtime_feedback_list shows where it stands and when it ships.","inputSchema":{"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."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$"}},"required":["kind","summary"],"additionalProperties":false}},{"name":"runtime_feedback_list","description":"List this organization's feedback reports, newest first, with the status (new, planned, shipped, declined) and ship note of the item each merged into. sorted false with item null means received and waiting to be sorted; sorting runs every hour. Read-only.","inputSchema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":500}},"required":[],"additionalProperties":false}},{"name":"runtime_support_message","description":"Ask Runtime's support agent when you are stuck: an error you cannot resolve, a sandbox that will not start, billing, how to do something, a migration question. It sees this account (with your permission for anything inside a sandbox) and can escalate to a person. Start with just message; continue with the returned conversationId. If status is working, wait about a minute and call runtime_support_read. It may propose an action (stop, wake, extend...): nothing runs until you pass approveActionId with its approveInputHash, which you should only do after the human you work for agrees. Deny with denyActionId.","inputSchema":{"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}},{"name":"runtime_support_read","description":"Read the latest state of a support conversation: status, the newest reply and any pending actions awaiting approval.","inputSchema":{"type":"object","properties":{"conversationId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"From a previous reply."}},"required":["conversationId"],"additionalProperties":false}},{"name":"runtime_sandbox_interpreter_run","description":"Run Python (default), JavaScript, TypeScript, R, Java, Bash or Go in a stateful interpreter inside a running sandbox. Variables and imports persist between calls to the same context, like a notebook cell (Go keeps declarations, not values). Returns stdout, stderr, results (text/plain, text/html, image/png base64 for matplotlib charts and R plots, application/vnd.runtime.table+json for DataFrames, R data frames and arrays of objects) and an error with traceback. R, Java and Go install themselves on first use when the image lacks them (tens of seconds, once). Use it for data analysis, charts and quick computations; use runtime_sandbox_exec for shell commands. Values over 48 KiB come back as refs to files in the sandbox. timeoutMs defaults to 300000.","inputSchema":{"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)."},"code":{"type":"string","maxLength":524288},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python (default), javascript, typescript, r, java, bash or go. R, Java and Go are installed in the sandbox on first use (tens of seconds, once) when its image lacks them."},"context":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id. Each language's name (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's default context, started on first use."},"timeoutMs":{"type":"integer","minimum":1,"maximum":3600000},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id","code"],"additionalProperties":false}},{"name":"runtime_sandbox_interpreter_contexts","description":"List, create, restart, interrupt or remove the interpreter contexts in a sandbox. A context is an isolated interpreter with its own variables; each language's name (python, javascript, typescript, r, java, bash, go) is the default context runtime_sandbox_interpreter_run starts on first use. action=list needs only id. restart clears a context's variables; interrupt stops the running cell and keeps them.","inputSchema":{"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)."},"action":{"type":"string","enum":["list","create","restart","interrupt","remove"]},"context":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$","description":"A context's id. Each language's name (`python`, `javascript`, `typescript`, `r`, `java`, `bash`, `go`) is that language's default context, started on first use."},"language":{"type":"string","enum":["python","javascript","typescript","r","java","bash","go"],"description":"python (default), javascript, typescript, r, java, bash or go. R, Java and Go are installed in the sandbox on first use (tens of seconds, once) when its image lacks them."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":4096},"maxProperties":64,"description":"Environment variables for the context's process."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_image_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}). Give `name` to version it: each build of a name is its next version and takes the tag latest (or `tags`). `start` sets what a sandbox from it runs and when its create answers ({command, readyPort | readyCommand}); a Dockerfile's CMD and HEALTHCHECK fill it in. Returns the image queued; call runtime_image_get until ready or failed, then create sandboxes with image set to its id or name:tag. A rebuild reuses the steps an earlier build shares.","inputSchema":{"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."},"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":1024,"maximum":32768,"default":4096,"description":"The build guest's own scratch disk: earlier stages and the context live here."},"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},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":[],"additionalProperties":false}},{"name":"runtime_image_get","description":"An image's state (queued, building, ready, failed), version, tags, size and error, with the last build log lines. id takes an id, name, name:tag or name@version. Give name alone to list that name's versions; omit both to list your images.","inputSchema":{"type":"object","properties":{"id":{"type":"string","maxLength":300,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","description":"An image id, a name (its latest tag), name:tag or name@version."},"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."},"logsAfter":{"type":"integer","minimum":0,"maximum":1000000}},"required":[],"additionalProperties":false}},{"name":"runtime_image_tag","description":"Point a tag (such as prod or v2) of an image's name at one version, moving it from wherever it was, or with remove: true take it off. Sandboxes then start from name:tag.","inputSchema":{"type":"object","properties":{"id":{"type":"string","maxLength":300,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","description":"An image id, a name (its latest tag), name:tag or name@version."},"tag":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$"},"remove":{"type":"boolean"}},"required":["id","tag"],"additionalProperties":false}},{"name":"runtime_image_registries","description":"List, store or forget the credentials image builds use to pull private images. action set: {registry, username, password} (Docker Hub, GitHub, Google: username _json_key with the key as password) or {registry, accessKeyId, secretAccessKey} for Amazon ECR. Secrets are sealed to Runtime's hosts and never returned.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","set","delete"]},"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":["action"],"additionalProperties":false}},{"name":"runtime_image_delete","description":"Delete an image version (by id, name:tag or name@version) and its tags. Sandboxes already started from it are not affected.","inputSchema":{"type":"object","properties":{"id":{"type":"string","maxLength":300,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@-]{0,299}$","description":"An image id, a name (its latest tag), name:tag or name@version."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_volume_create","description":"Create a persistent disk (sizeMiB 64 to 1048576) that outlives sandboxes, or restore one from a backup with fromBackup (then omit sizeMiB). Attach it when creating a sandbox with volumes: [{volumeId: id, path: \"/data\"}] (read-write, one sandbox at a time) or mode \"snapshot\" (a read-only copy as it is now, any number of sandboxes). 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.","inputSchema":{"type":"object","properties":{"sizeMiB":{"type":"integer","minimum":64,"maximum":1048576},"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":"Resource identifier (UUID)."},"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."},"region":{"type":"string"},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":[],"additionalProperties":false}},{"name":"runtime_volume_get","description":"One volume by id, or omit id to list them: size, space used, attachments, backups.","inputSchema":{"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)."}},"required":[],"additionalProperties":false}},{"name":"runtime_volume_delete","description":"Delete a volume and all its data. Refused while a sandbox holds it; delete that sandbox first. Its backups are kept for their retention.","inputSchema":{"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)."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_volume_backup","description":"Back a volume up now, off its host: a crash-consistent point in time, kept retentionDays (the volume's retention, 7 unless set). Waits up to a minute for it to be ready. Restore it with runtime_volume_create and fromBackup.","inputSchema":{"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)."},"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."},"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","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["volumeId"],"additionalProperties":false}},{"name":"runtime_volume_backup_get","description":"One volume backup by id, or omit id to list them (optionally those of one volumeId): state, size, stored bytes, expiry.","inputSchema":{"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)."},"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)."}},"required":[],"additionalProperties":false}},{"name":"runtime_volume_backup_policy","description":"Turn a volume's daily backups on or off (daily) and set how many days each is kept (retentionDays, 1 to 365).","inputSchema":{"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)."},"daily":{"type":"boolean"},"retentionDays":{"type":"integer","minimum":1,"maximum":365},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["volumeId"],"additionalProperties":false}},{"name":"runtime_volume_backup_delete","description":"Delete a volume backup and its copy off the host.","inputSchema":{"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)."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_snapshot_create","description":"Keep a paused sandbox's files, memory and running processes for copies; it is also copied off its host, so it survives losing that host. Sandboxes with volumes cannot be snapshotted. To install dependencies once for sandboxes on any host, build an image with runtime_image_build instead. Ordinary sandbox pause/wake and management of existing catalog records are separate operations. fork_unavailable means an operator has switched snapshots off; it is not retryable.","inputSchema":{"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":"Resource identifier (UUID)."},"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."},"retentionDays":{"type":"integer","minimum":1,"maximum":365,"description":"Days to keep it, 1 to 365; 7 when omitted. Never past a year from when it was taken."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["sandboxId"],"additionalProperties":false}},{"name":"runtime_snapshot_get","description":"One snapshot by id, or omit id to list them (optionally those of one sandboxId): state, shape, stored bytes, expiry.","inputSchema":{"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)."},"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":"Resource identifier (UUID)."}},"required":[],"additionalProperties":false}},{"name":"runtime_snapshot_delete","description":"Delete a snapshot and free its storage. Sandboxes already started from it keep running.","inputSchema":{"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)."},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_mount","description":"Mount an S3 (provider s3, region), Cloudflare R2 (provider r2, accountId) or Google Cloud Storage (provider gcs, HMAC keys) bucket at path in a running sandbox. secret names a stored secret with header Authorization, format \"AWS4-HMAC-SHA256 {value}\", value ACCESS_KEY_ID:SECRET_KEY and the endpoint host in its hosts: the sandbox never sees the key. Omit secret for a public bucket.","inputSchema":{"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)."},"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":["id","provider","bucket","path"],"additionalProperties":false}},{"name":"runtime_sandbox_mounts","description":"The buckets mounted in a sandbox, and whether each is mounted now.","inputSchema":{"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)."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_unmount","description":"Unmount the bucket mounted at path. What was written stays in the bucket.","inputSchema":{"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)."},"path":{"type":"string"}},"required":["id","path"],"additionalProperties":false}},{"name":"runtime_sandbox_previews_create","description":"Give a port inside a sandbox (a web server, an API, a dev server) a public HTTPS address, https://<port>-<sandbox>.<domain>/. visibility private (default) needs the returned token: send it as the x-runtime-preview-token header, or open urlWithToken in a browser. public needs nothing; browsers see a one-time Runtime warning page. WebSockets work. Idempotent per port. The answer's hint says how to share it.","inputSchema":{"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)."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."},"visibility":{"type":"string","enum":["private","public"],"description":"private (default): a token is needed. public: anyone with the address."},"ttlSeconds":{"type":"integer","minimum":60,"maximum":604800,"default":86400,"description":"How long the token lasts, in seconds. One day unless asked; a week at most."}},"required":["id","port"],"additionalProperties":false}},{"name":"runtime_sandbox_previews_list","description":"List the ports a sandbox shares, each with its URL and, if private, a fresh token. Read-only.","inputSchema":{"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)."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_previews_delete","description":"Remove a sandbox's preview for one port. Its URL stops answering within seconds.","inputSchema":{"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)."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."}},"required":["id","port"],"additionalProperties":false}},{"name":"runtime_sandbox_network_set","description":"Turn a sandbox's internet off or on, and limit it to (allow) or keep it from (deny) domains, *.domains, addresses or CIDR ranges. A paid sandbox of an organization with a paid purchase reaches every port (databases, ssh, gRPC), and allow and deny narrow every port; a trial sandbox reaches ports 80 and 443. connect lists extra host:port pairs such as db.example.com:5432. Applies at once, to open connections too. Private addresses are always refused. Returns the rules, whether the host enforces them, and openPorts.","inputSchema":{"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)."},"internet":{"type":"boolean"},"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},"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},"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}},"required":["id","internet"],"additionalProperties":false}},{"name":"runtime_sandbox_network_get","description":"Read a sandbox's network rules (internet, allow, deny, connect), whether its host enforces the latest version, and whether host:port reach is open to this organization. Read-only.","inputSchema":{"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)."}},"required":["id"],"additionalProperties":false}},{"name":"runtime_domain_add","description":"Serve a port of a sandbox at your own hostname (app.example.com) with automatic HTTPS. Returns the DNS records to set: a TXT record proving ownership and a CNAME (A record for an apex). Checks the TXT record at once; call runtime_domain_verify after setting DNS. Paid accounts only.","inputSchema":{"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 that serves it."},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The port your server listens on inside the sandbox."}},"required":["hostname","sandboxId","port"],"additionalProperties":false}},{"name":"runtime_domain_verify","description":"Look up the domain's TXT record now and activate it when it matches; also says whether the name points at Runtime yet.","inputSchema":{"type":"object","properties":{"hostname":{"type":"string","maxLength":253}},"required":["hostname"],"additionalProperties":false}},{"name":"runtime_domain_list","description":"Your custom domains with their state and DNS records. Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_domain_remove","description":"Stop serving a custom domain. Remove its DNS records at your DNS provider too.","inputSchema":{"type":"object","properties":{"hostname":{"type":"string","maxLength":253}},"required":["hostname"],"additionalProperties":false}},{"name":"runtime_port_open","description":"Give a port inside a sandbox (Postgres, Redis, a game server, anything not HTTP) a public address:port for raw TCP. Idempotent per sandbox and port. Paid accounts only.","inputSchema":{"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}},{"name":"runtime_port_list","description":"Your public TCP ports, or one sandbox's. Read-only.","inputSchema":{"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":"Resource identifier (UUID)."}},"required":[],"additionalProperties":false}},{"name":"runtime_port_close","description":"Close a public TCP port by its portId (from runtime_port_open or runtime_port_list). Open connections end within seconds.","inputSchema":{"type":"object","properties":{"portId":{"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)."}},"required":["portId"],"additionalProperties":false}},{"name":"runtime_address_reserve","description":"Every sandbox of your organization then sends from one address of its own, for allow-lists. family 4 (default) or 6. Idempotent. Paid accounts only.","inputSchema":{"type":"object","properties":{"family":{"type":"integer","minimum":4,"maximum":6}},"required":[],"additionalProperties":false}},{"name":"runtime_address_list","description":"Your organization's dedicated outbound addresses. Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_address_release","description":"Give a dedicated outbound address back by its addressId; sandboxes send from the shared addresses again at once.","inputSchema":{"type":"object","properties":{"addressId":{"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)."}},"required":["addressId"],"additionalProperties":false}},{"name":"runtime_tunnel_get","description":"Your WireGuard tunnel (private network): endpoint, gateway key, peers, and each sandbox's private address. Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_tunnel_create","description":"Create a WireGuard private network from your own network into your sandboxes. subnet defaults to 10.250.0.0/16. Idempotent. Paid accounts only.","inputSchema":{"type":"object","properties":{"subnet":{"type":"string","maxLength":18}},"required":[],"additionalProperties":false}},{"name":"runtime_tunnel_add_peer","description":"Add a machine or router of yours and get its wg-quick file (config). Leave publicKey out to have Runtime generate the key pair; the private key is then in config, shown once. routes: your own ranges sandboxes may reach through it.","inputSchema":{"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}},{"name":"runtime_tunnel_rotate_peer","description":"Give a peer a new key; the old one stops working within seconds. Returns the new config.","inputSchema":{"type":"object","properties":{"peerId":{"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)."},"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":["peerId"],"additionalProperties":false}},{"name":"runtime_tunnel_remove_peer","description":"Revoke a peer by its peerId: its tunnel and connections end within seconds.","inputSchema":{"type":"object","properties":{"peerId":{"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)."}},"required":["peerId"],"additionalProperties":false}},{"name":"runtime_sandbox_desktop_record","description":"Record a sandbox's desktop to an MP4 file. action=start (fps, maxSeconds, maxMiB, crf) begins and returns the recording id; action=stop (recordingId) finishes the file; action=list; action=delete (recordingId). The video is at path in the sandbox; download it from GET /v1/sandboxes/{id}/desktop/recordings/{recordingId}/video or with runtime sandbox 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","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)."},"action":{"type":"string","enum":["start","stop","list","delete"]},"recordingId":{"type":"string","pattern":"^rec-[a-z0-9]{8,32}$","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_sandbox_desktop_screenshot","description":"Take a screenshot of a sandbox's Linux desktop. Returns base64 image data and its MIME type. Start the desktop first with runtime_sandbox_desktop_act, action start.","inputSchema":{"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)."},"format":{"type":"string","enum":["png","jpeg"]}},"required":["id"],"additionalProperties":false}},{"name":"runtime_sandbox_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 Firefox; launch a program. Take runtime_sandbox_desktop_screenshot to see the result.","inputSchema":{"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)."},"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},"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 Firefox."},"argv":{"type":"array","items":{"type":"string","maxLength":4096},"maxItems":64,"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_sandbox_mcp","description":"action=catalog lists the MCP servers that can run (GitHub, Postgres, Playwright browser, filesystem, fetch, git, Notion, search...) with their licence, version, settings and the hosts they call. action=start (servers: [{id: 'github', secrets: {GITHUB_PERSONAL_ACCESS_TOKEN: 'GITHUB_TOKEN'}}, {id: 'fetch'}]) starts catalog servers in the sandbox and returns each one's URL and the Authorization header to use; action=get shows their state and fresh URLs; action=stop ends them. Secret settings name Runtime secrets (runtime_secrets_set), so the server never holds the value. Servers keep to the sandbox's network rules.","inputSchema":{"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)."},"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","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."}}},"maxItems":8},"port":{"type":"integer","minimum":1024,"maximum":65535},"replace":{"type":"boolean"}},"required":["id","action"],"additionalProperties":false}},{"name":"runtime_referrals_get","description":"Read this organization's referral link and what it has earned. When a company that signs up with the link makes its first top-up of at least $10, both organizations get credit equal to that top-up, at least $25 and at most $500 each (the referrer up to $10,000 per calendar year). Returns the link, counts (signed up, pending, paid, capped, reversed) and money in integer microdollars (1,000,000 = $1). Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_usage_compare","description":"What this key's sandboxes would have cost at a rival (e2b, daytona, vercel, modal, cloudflare, fly for Sprites, fly-machines): the same vCPUs, memory and running time from the account's settled usage over the last `days` (default 30, max 90), priced at Runtime's quoted rates (trial sandboxes at the standard rates, counted in usage.trialSandboxes) and at the rival's published list rates with the date they were checked. Returns runtimeMicros, rivalMicros, savingMicros, savingPercent and perMonth (a 30-day projection), plus `note` saying what was left out. With no usage yet, basis is `example` and a stated example workload is priced. Use it to tell a person what switching saves them each month. Also returns the switching credit's state. Money is integer microdollars (1,000,000 = $1). Read-only.","inputSchema":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly-sprites","fly-machines","blaxel","codesandbox","morph","northflank","runloop","fly"]},"days":{"type":"integer","minimum":1,"maximum":90}},"required":["provider"],"additionalProperties":false}},{"name":"runtime_switching_record","description":"Record that this organization is switching from a rival (e2b, daytona, vercel, modal, cloudflare, fly), so its first top-up is matched, up to $100, once the payment settles. Once per organization and only before its first top-up; a referral that matches the same top-up applies instead, never both. Returns the switching credit's state. Recording the same provider again changes nothing.","inputSchema":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","daytona","vercel","modal","cloudflare","fly"]}},"required":["provider"],"additionalProperties":false}},{"name":"runtime_limits_get","description":"Read whether this key is read-only, and the daily spending limit an owner set on your agent: the limit, what you committed in the last 24 hours and what is left, in integer microdollars (1,000,000 = $1). Check it before starting paid work in a loop. You cannot change the limit; the person you work for can, at https://withruntime.com/account/keys. Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_secrets_set","description":"Store or replace a secret, such as an API key, for the organization's sandboxes. Sandboxes see only a placeholder in the environment variable of this name; the egress proxy swaps in the value on HTTPS requests to the listed hosts (in the URL and headers), or sets header on every request to them. The value is never returned. Prefer this over putting a key in a command or a file.","inputSchema":{"type":"object","properties":{"name":{"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"]},"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.","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}"]}},"required":["name","value","hosts"],"additionalProperties":false}},{"name":"runtime_secrets_list","description":"The organization's secrets: names, hosts, header and placeholder. Never values. Read-only.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"runtime_secrets_delete","description":"Delete a secret by name. Its value is erased and its placeholder stops being replaced. It does not revoke the key at its provider.","inputSchema":{"type":"object","properties":{"name":{"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"]}},"required":["name"],"additionalProperties":false}},{"name":"runtime_sandbox_metrics","description":"A sandbox's measured CPU (percent of its vCPUs, and cores) and resident memory over a range (15m, 1h, 6h, 24h, 7d, 30d; 1h when omitted), with the latest reading. Use it to size a sandbox, to see whether a process is busy or stuck, or to find what drove a bill. Read-only.","inputSchema":{"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)."},"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, 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. Read-only.","inputSchema":{"type":"object","properties":{"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)."},"type":{"type":"string","enum":["sandbox.created","sandbox.running","sandbox.paused","sandbox.woken","sandbox.stopped","sandbox.start_failed","sandbox.wake_failed","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]},"cursor":{"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)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size, 1 to 100."}},"required":[],"additionalProperties":false}},{"name":"runtime_webhooks_manage","description":"Manage the account's webhooks, which POST signed lifecycle events (sandbox.created, sandbox.running, sandbox.paused, sandbox.woken, sandbox.stopped, sandbox.start_failed, sandbox.wake_failed, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted) to an https URL. action: \"list\"; \"get\" (id); \"create\" (url, optional events and description; returns the signing secret once, keep it); \"update\" (id and any of url, events, description, enabled); \"rotate_secret\" (id, optional keepPreviousSeconds); \"delete\" (id); \"test\" (id: sends a signed webhook.test now and returns your endpoint's answer); \"deliveries\" (id: recent deliveries and answers); \"retry\" (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","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)."},"deliveryId":{"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)."},"url":{"type":"string","maxLength":2048,"pattern":"^https://","description":"An https URL on the public internet."},"description":{"type":"string","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","snapshot.ready","snapshot.failed","snapshot.deleted","volume.ready","volume.failed","volume.deleted"]},"minItems":1,"maxItems":32,"description":"Which events to send: any of sandbox.created, sandbox.running, sandbox.paused, sandbox.woken, sandbox.stopped, sandbox.start_failed, sandbox.wake_failed, snapshot.ready, snapshot.failed, snapshot.deleted, volume.ready, volume.failed, volume.deleted; or [\"*\"] for every type, including ones added later (the default)."},"enabled":{"type":"boolean"},"keepPreviousSeconds":{"type":"integer","minimum":0,"maximum":604800},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_otel_manage","description":"Manage exports that push sandbox events (as OTLP logs) and CPU and memory (as OTLP metrics) to an OpenTelemetry endpoint over OTLP/HTTP JSON. action: \"list\"; \"get\" (id); \"create\" (endpoint: the OTLP base URL, e.g. https://otlp-gateway-prod-us-east-0.grafana.net/otlp; headers for its authentication; signals, both by default); \"update\" (id and any of endpoint, headers, signals, enabled); \"flush\" (id: push now); \"delete\" (id). Header values are never shown back.","inputSchema":{"type":"object","properties":{"action":{"type":"string","enum":["list","get","create","update","flush","delete"]},"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)."},"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."},"enabled":{"type":"boolean"},"idempotencyKey":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$","description":"Resource identifier."}},"required":["action"],"additionalProperties":false}},{"name":"runtime_audit_list","description":"Read the account's audit log, newest first: who changed members and roles, created or revoked keys, approved connections, added or refunded credit, changed network rules or secrets, or deleted a volume, image or snapshot, with the time, the client address and the request id. Filter with action (key.created) or a group (member., key., credit., network., secret.). Page with before = the previous page's next. Needs a key made by an owner or admin. Read-only.","inputSchema":{"type":"object","properties":{"before":{"type":"string","pattern":"^[1-9][0-9]{0,18}$","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","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.."}},"required":[],"additionalProperties":false}},{"name":"runtime_account_sso_get","description":"Read the account's single sign-on: each identity provider (Okta, Microsoft Entra ID, Google Workspace or other, over OIDC or SAML), the email domain it answers for, whether that domain is proven by its DNS TXT record (and the record to add if not), the role new people join with, whether SSO is required, and SCIM directory sync (tokens, people, groups and the role each gives). Read-only: an owner changes it on the website. Needs a key made by an owner or admin.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}]}