{"components":{"headers":{"RateLimitLimit":{"description":"Requests allowed in the current window.","schema":{"minimum":0,"type":"integer"}},"RateLimitPolicy":{"description":"The policy, RFC 9745 form: \";w=\".","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Requests left in the current window.","schema":{"minimum":0,"type":"integer"}},"RateLimitReset":{"description":"Seconds until the window refills.","schema":{"minimum":0,"type":"integer"}},"RequestId":{"description":"This request's id. Quote it in a support ticket and the logs line up.","schema":{"pattern":"^req_[0-9a-f]{32}$","type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"minimum":0,"type":"integer"}}},"parameters":{"Workspace":{"description":"Act in this workspace (its slug). Omitted: the token's bound workspace, then the organization's default. Never ambient - there is no switch-workspace mutation on this door.","in":"query","name":"workspace","required":false,"schema":{"pattern":"^[a-z0-9-]+$","type":"string"}}},"responses":{"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.","headers":{"request-id":{"$ref":"#/components/headers/RequestId"}}},"Internal":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Our fault. Retry; if it persists, quote the request-id. Code `internal`.","headers":{"request-id":{"$ref":"#/components/headers/RequestId"}}},"Invalid":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.","headers":{"request-id":{"$ref":"#/components/headers/RequestId"}}},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such route. Code `not_found`; the body names the OpenAPI document."},"RateLimited":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"Refused":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.","headers":{"request-id":{"$ref":"#/components/headers/RequestId"}}},"Settling":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The node changed state under every pass this call made - a wake, a stop, or a container exit landing mid-call. Nothing ran and nothing was billed; the same call works shortly. Wait `Retry-After` seconds and repeat it. Code `settling`.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"Unauthenticated":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No bearer token, or one this API cannot verify. Code `unauthenticated`.","headers":{"request-id":{"$ref":"#/components/headers/RequestId"}}}},"schemas":{"Error":{"description":"The one error shape this API has, on every 4xx and 5xx. `message` is the same teaching text the MCP door serves, written to be read by whoever has to act on it.","properties":{"error":{"properties":{"code":{"description":"A machine-readable class. The vocabulary is OPEN: treat a code you do not know as a generic failure of its HTTP status rather than an error.","examples":["unauthenticated","forbidden","invalid","refused","not_found","rate_limited","internal","settling"],"type":"string"},"message":{"description":"What went wrong and what to do about it, in prose. Safe to show a human verbatim.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"List":{"description":"The list envelope every paging endpoint returns.","properties":{"items":{"items":{"$ref":"#/components/schemas/Result"},"type":"array"},"next_cursor":{"description":"Pass as ?cursor= for the next page. Absent on the last page. Opaque: never parse it.","type":"string"},"object":{"const":"list"}},"required":["object","items"],"type":"object"},"Result":{"additionalProperties":true,"description":"The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.","properties":{"object":{"description":"The resource type, when the result is one resource.","type":"string"}},"type":"object"}},"securitySchemes":{"bearerAuth":{"description":"The same bearer tokens the MCP door verifies. `gman login` mints one interactively; POST /preview/org/tokens vends a service token. A token's scopes decide which operations it may call; a refusal names the scope word to request.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"The manual, plus /llms.txt for the same contract written for an agent.","url":"https://autoresearch.sfcompute.com/docs"},"info":{"contact":{"name":"givemeanode support","url":"https://autoresearch.sfcompute.com/contact"},"description":"PREVIEW: the contract may move until launch, when these routes are promoted verbatim to /v1 and /preview becomes a deprecated alias (GMAN-31). Same capability core as the MCP door: each operation names its capability in x-capability, takes the same parameters as the tool's inputSchema (path/query parameters overlay the JSON body), and returns the tool's structuredContent. Auth: the same bearer tokens as the MCP door. Conventions: resources carry an 'object' type discriminator and immutable ids; money crosses the wire as integer micro-dollars (*_usd_micros; dollar floats/strings are display only); the accelerator field is 'chip', which takes a node type's name (\"h100-1\", \"h100-8\", \"cpu-2\", \"cpu-8\"; the GPU types' original spellings \"h100\" and \"8xh100\" are accepted too and are what responses echo). Workspace binding is per request via ?workspace=, never ambient. List endpoints page with ?cursor=&limit= returning {object: 'list', items, next_cursor?}. Logs are offset-polled (?offset=), never streamed. Every response carries a request-id header and the RateLimit header set; 429s carry Retry-After; POST /jobs honors the Idempotency-Key header. See x-versioning for how this contract changes and x-rate-limits for the budgets.","license":{"name":"Proprietary","url":"https://autoresearch.sfcompute.com/tos"},"summary":"On-demand GPU nodes, batch jobs, sweeps, and sandboxes, REST-shaped for CLIs and scripts.","title":"givemeanode customer API","version":"preview"},"openapi":"3.1.0","paths":{"/preview/alerts":{"put":{"description":"Set this workspace's two money-safety alerts (a full replace: omitted thresholds turn that alert off). Idle-burn: email (+ optional webhook, + optional auto-stop) when a node bills with every GPU under idle_burn_util_pct% for idle_burn_minutes observed minutes - the watchdog you no longer have to hand-roll, and it cannot die silently because the platform that bills is the platform that watches. Budget: fire once per month when MTD spend crosses budget_warn_pct% of the governing cap.","operationId":"put_set_alerts","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"budget_warn_pct":{"default":null,"description":"Budget: fire once per month when MTD spend crosses this percent of\nthe workspace (or org) hard cap. Omit to turn it off.","format":"int32","type":["integer","null"]},"idle_burn_auto_stop":{"default":null,"description":"Stop the node automatically when idle-burn fires (the policy-stop\npath: files intact, next command wakes it). Default false.","type":["boolean","null"]},"idle_burn_minutes":{"default":null,"description":"...for this many consecutive observed minutes (>= 5).","format":"int32","type":["integer","null"]},"idle_burn_util_pct":{"default":null,"description":"Idle-burn: fire when every GPU on a billing node stays under this\nutilization percent... (1-100). Omit to turn idle-burn off.","format":"int32","type":["integer","null"]},"webhook_url":{"default":null,"description":"Optional https webhook POSTed alert JSON alongside the email.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Replace the workspace's alert policy (omit a threshold to turn it off)","tags":["alerts"],"x-capability":"set_alerts"}},"/preview/artifacts/{id}":{"get":{"description":"Fetch an artifact's record and a fresh download URL by id - the way back to an export after the original export_file response is gone (a mission page lists artifact ids; this turns one back into bytes). Returns the export_file shape: {artifact_id, state, source_path, size_bytes, sha256, download: {url, expires_at}} for a ready artifact (a fresh ~7-day presigned GET; the stored object itself lives ~30 days, after which the download is omitted and re-exporting is the fix). Pending shows its state, failed its error; a capture that landed in your own store or platform storage shows where it went instead of a link. To put the file in front of a human (Slack, a doc, ), share_artifact mints a public embeddable link instead.","operationId":"get_get_artifact","parameters":[{"description":"The art-... id returned by export_file / copy_file / get_job (or\nlisted on get_mission).","in":"path","name":"id","required":true,"schema":{"description":"The art-... id returned by export_file / copy_file / get_job (or\nlisted on get_mission).","type":"string"},"x-property":"artifact_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"An earlier export's record and a fresh download URL","tags":["artifacts"],"x-capability":"get_artifact"}},"/preview/artifacts/{id}/shares":{"post":{"description":"Make one exported artifact PUBLIC at a clean, embeddable URL - the way to put a file in front of a human in another tool. Where export_file's presigned URL is private, unwieldy, and only good for curl, the share URL (https://s.givemeanode.io/shr-.../cat1.jpg) carries the real filename, the real content type, and no query string: paste it in Slack and an image unfurls inline; works; browsers render rather than download. Returns {share_id, url, filename, content_type, size_bytes, expires_at}. The bytes are FROZEN at share time (a copy, so the link outlives the export's ~30-day object), the link lives 365 days by default (expires_after: \"48h\"..\"365d\" chooses; re-sharing the same artifact refreshes the same URL's expiry), and unshare(share_id) revokes it any time - list_shares shows everything your org has public. ANYONE holding the URL can fetch the file: sharing is a deliberate, audited decision, never a default. Images, PDFs, video, audio, and plain text render inline; HTML and SVG never do (they download instead); anything else is a clean named download. Directory exports share as a .tar. Bounded per org in size, rate, and count (refusals name the limit).","operationId":"post_share_artifact","parameters":[{"description":"The art-... id of a READY artifact (from export_file, copy_file's\nexport leg, get_job's output capture, or get_mission).","in":"path","name":"id","required":true,"schema":{"description":"The art-... id of a READY artifact (from export_file, copy_file's\nexport leg, get_job's output capture, or get_mission).","type":"string"},"x-property":"artifact_id"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"expires_after":{"default":null,"description":"How long the link lives, a duration like \"48h\" or \"90d\" (minimum\n1h, default 365d, bounded by the share_ttl_days_max limit). The\nlink dies at expiry; unshare kills it sooner.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Make one exported artifact public at an embeddable URL","tags":["artifacts"],"x-capability":"share_artifact"}},"/preview/audit/events":{"get":{"description":"The organization's audit log as customer-facing events (WorkOS Events API shape): every decision that changed something - node create/stop/delete, job submissions, invites, role changes, cap changes, credits, dunning - who did it, from which surface, and when. Admin and billing roles see the whole org; members see their own decisions. Newest first by default; pass `after` from `list_metadata.after` to page older, or order:\"asc\" to walk oldest-to-newest (the sync/tail order: keep polling with the last cursor to stream new events). History reaches back 24 months. Every row names its actor, so `data.actor.type` answers \"my key or the platform?\": `customer`/`service_token` is one of your people, `operator` is Autoresearch staff, and `system` is the platform acting on its own - which it does only to END a node nobody asked it to end (idle grace lapsing, the container dying, a host death, a queued wake's hold expiring). The `system` rows are org-scoped and nobody's authorship, so reading them needs the admin or billing role; a member sees only their own. `data.context.request_id` is the same id the API returns in the `request-id` header, so a row you did cause joins back to the call that caused it. NOTE there is no wake tool: run_command, write_file and node_doctor WAKE a stopped node as a side effect, and the node.wake row's `details.trigger` names which one did it. Other telemetry (heartbeats, meter ticks, and every non-ending transition - scheduled, ready, sessions attaching) is never here - node history lives on get_node.","operationId":"get_list_audit_events","parameters":[{"description":"Only these event names (dot-namespaced actions, e.g.\n[\"node.stop\", \"member.invite\"]). Omitted = every event.","in":"query","name":"events","required":false,"schema":{"default":null,"description":"Only these event names (dot-namespaced actions, e.g.\n[\"node.stop\", \"member.invite\"]). Omitted = every event.","items":{"type":"string"},"type":["array","null"]}},{"description":"Only one actor's events: a member's customer id (exact) or a\ncase-insensitive fragment of their email/display name.","in":"query","name":"actor","required":false,"schema":{"default":null,"description":"Only one actor's events: a member's customer id (exact) or a\ncase-insensitive fragment of their email/display name.","type":["string","null"]}},{"description":"Trailing window, e.g. \"48h\", \"30m\", \"7d\" - sugar for range_start.","in":"query","name":"since","required":false,"schema":{"default":null,"description":"Trailing window, e.g. \"48h\", \"30m\", \"7d\" - sugar for range_start.","type":["string","null"]}},{"description":"Only events at or after this RFC 3339 timestamp.","in":"query","name":"range_start","required":false,"schema":{"default":null,"description":"Only events at or after this RFC 3339 timestamp.","type":["string","null"]}},{"description":"Only events at or before this RFC 3339 timestamp.","in":"query","name":"range_end","required":false,"schema":{"default":null,"description":"Only events at or before this RFC 3339 timestamp.","type":["string","null"]}},{"description":"\"desc\" (default: newest first) or \"asc\" (oldest first - the\nsync/tail order: walk forward by passing each page's\n`list_metadata.after`, then poll with the last cursor for new\nevents).","in":"query","name":"order","required":false,"schema":{"default":null,"description":"\"desc\" (default: newest first) or \"asc\" (oldest first - the\nsync/tail order: walk forward by passing each page's\n`list_metadata.after`, then poll with the last cursor for new\nevents).","type":["string","null"]}},{"description":"Max events to return (default 50, cap 100).","in":"query","name":"limit","required":false,"schema":{"default":null,"description":"Max events to return (default 50, cap 100).","format":"int64","type":["integer","null"]}},{"description":"Resume after this event id (the previous page's\n`list_metadata.after`) - keyset pagination.","in":"query","name":"after","required":false,"schema":{"default":null,"description":"Resume after this event id (the previous page's\n`list_metadata.after`) - keyset pagination.","type":["string","null"]}},{"description":"Organization: an org uuid or an org name from your memberships;\nomitted = your active org.","in":"query","name":"org","required":false,"schema":{"default":null,"description":"Organization: an org uuid or an org name from your memberships;\nomitted = your active org.","type":["string","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The org's audit log as events (WorkOS Events shape; ?events=&since=&order=&after=)","tags":["audit"],"x-capability":"list_audit_events"}},"/preview/billing":{"get":{"description":"Your organization's billing posture, read-only: dunning state (why provisions might be refused), month-to-date spend - INCLUDING usage in progress, so it runs ahead of get_usage's `total_usd`, which counts only what has billed (get_usage's `spend_so_far_usd` is this same figure) - spend caps, and (for admin/billing roles) payment method status, collection method, credit balance, per-member spend, any prepaid-contract balance with its expiry (distinct from pooled credits - the figure to track against a prepay deal), and cash received in every shape (usage invoices, contract invoices, wires). Members see the org's dunning state plus their own numbers; org-wide money is role-gated exactly like the /usage page. Card and invoice changes are ceremonies: they live in the billing portal (the response carries the link).","operationId":"get_get_billing","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"description":"Organization: an org uuid or an org name from list_team's\nmemberships; omitted = your active org.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Billing state: caps, dunning, portal URL","tags":["billing"],"x-capability":"get_billing"}},"/preview/connections":{"get":{"description":"Your org's stored data connections, BY NAME ONLY - the access they grant is exercised only by the platform and is never shown to you or anyone: there is nothing here to paste anywhere. Returns [{name, kind, verbs, scope, auth, disabled, last_used_at}], e.g. {name: \"acme-corpus\", kind: \"s3-keys\", verbs: [\"read\"], scope: \"s3://acme-ml/corpus-v3/*\", auth: \"token\"} (auth \"oauth\" = a browser grant, no stored secret at all; one still pending its browser step shows pending_authorization: true and can't import yet). Use a name with import_data to land private data on a node without ever holding a credential. A kind \"registry\" row is different: it is a private Docker registry, exercised when a JOB pulls an image inside its scope, so you never name it anywhere - just pass the image to submit_job(image:) and the platform authenticates the pull. Empty, or missing the source you need? A human org admin adds one from their own terminal or CI - `gman connection create` (install: `curl -fsSL https://givemeanode.com/cli.sh | bash`, then `gman login`) - a one-time step, ~2 minutes, good for every future task. Ask them to do exactly that; NEVER ask anyone to paste a token, key, or password into this chat (transcripts are recorded and outlive the task), and connection mutations are not callable with this connection's grant.","operationId":"get_list_connections","parameters":[{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","type":"string"}},{"description":"Rows per page. Clamped to the range shown.","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Rows per page. Clamped to the range shown.","maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The org's data connections, names + scopes only (never material)","tags":["connections"],"x-capability":"list_connections"},"post":{"description":"Create a connection (material in body, sealed on arrival) [org:write + admin; this door only]","operationId":"post_create_connection","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"access_key_id":{"default":null,"description":"s3-keys identity.","type":["string","null"]},"auth":{"default":null,"description":"How access is established: \"token\" (a pasted secret, the default)\nor \"oauth\" (huggingface only - a browser consent dance through\nWorkOS Pipes; no material exists anywhere our side, tokens are\nminted at use).","type":["string","null"]},"endpoint":{"default":null,"type":["string","null"]},"header":{"default":null,"description":"https identity: the header the material rides (default\n\"authorization\", value \"Bearer \").","type":["string","null"]},"kind":{"type":"string"},"material":{"default":null,"description":"The secret half (s3 secret key, HF token, bearer). Sealed on\narrival, never echoed by anything. NEVER an MCP parameter - this\nstruct is deliberately not a tool schema.","type":["string","null"]},"name":{"type":"string"},"org":{"default":null,"description":"Act in this org (uuid or name); omitted = the bound/active org.","type":["string","null"]},"region":{"default":null,"type":["string","null"]},"scope":{"description":"The human-facing scope pin (e.g. \"s3://acme-ml/corpus-v3/\",\n\"acme/*\", \"https://data.corp.example/exports/\").","type":"string"},"username":{"default":null,"description":"registry identity: the login name the token belongs to - a GHCR\nusername, a Quay/Harbor robot account, \"_json_key\" for a GCP\nArtifact Registry service-account key. Non-secret; the token\nitself rides `material`.","type":["string","null"]},"validate":{"default":null,"description":"Live-validate against the provider before saving (s3-keys: a\none-object listing under the pin). Default true; Terraform-ish\nbootstrap passes false.","type":["boolean","null"]},"verbs":{"default":null,"description":"What the connection may do: [\"read\"] (the default) or\n[\"read\", \"write\"] (docs/designs/secrets.md: write enables export_data pushes\nto the pin). The customer's own provider policy is the real wall;\nthis is our enforcement of intent.","items":{"type":"string"},"type":["array","null"]}},"required":["name","kind","scope"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Create a connection (material in body, sealed on arrival) [org:write + admin; this door only]","tags":["connections"],"x-capability":"create_connection"}},"/preview/connections/{name}":{"delete":{"description":"Delete a connection (material shredded immediately) [org:write + admin; this door only]","operationId":"delete_delete_connection","parameters":[{"description":"The `name` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Delete a connection (material shredded immediately) [org:write + admin; this door only]","tags":["connections"],"x-capability":"delete_connection"},"get":{"description":"One connection: kind, scope, identity - never material [org:write + admin; this door only]","operationId":"get_get_connection","parameters":[{"description":"The `name` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"One connection: kind, scope, identity - never material [org:write + admin; this door only]","tags":["connections"],"x-capability":"get_connection"}},"/preview/connections/{name}/arm":{"post":{"description":"Replace a connection's material (re-key) [org:write + admin; this door only]","operationId":"post_arm_connection","parameters":[{"description":"The `name` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"material":{"default":null,"description":"Replacement material; sealed on arrival (the re-key path - name,\nkind, and scope survive). Absent on an OAuth connection: arming one\nmints a fresh authorization link instead (the re-consent path).","type":["string","null"]},"org":{"default":null,"type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Replace a connection's material (re-key) [org:write + admin; this door only]","tags":["connections"],"x-capability":"arm_connection"}},"/preview/connections/{name}/disable":{"post":{"description":"Disable a connection (in-flight imports fail honestly) [org:write + admin; this door only]","operationId":"post_disable_connection","parameters":[{"description":"The `name` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Disable a connection (in-flight imports fail honestly) [org:write + admin; this door only]","tags":["connections"],"x-capability":"disable_connection"}},"/preview/connections/{name}/enable":{"post":{"description":"Re-enable a disabled connection [org:write + admin; this door only]","operationId":"post_enable_connection","parameters":[{"description":"The `name` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Re-enable a disabled connection [org:write + admin; this door only]","tags":["connections"],"x-capability":"enable_connection"}},"/preview/contexts":{"get":{"description":"Your workspace's uploaded contexts, newest first: {context_id, sha256, size_bytes, status, created_at, finalized_at, lifecycle_expires_at}. The enumeration create_context/get_context never had - use it to find what you uploaded when the ids are no longer in your context, and to decide what to delete_context. Contexts live in the workspace they were created in (like nodes and artifacts): another workspace's uploads are not listed here and their ids answer as unknown. `status` is get_context's vocabulary (uploading / finalizing-or-failed / ready / expired / deleted); `lifecycle_expires_at` is when a finalized context stops being fetchable (~30 days after finalize). Pass include_deleted:true to see purge tombstones and their bytes_deleted_at confirmations.","operationId":"get_list_contexts","parameters":[{"description":"Max contexts to return (default 50, cap 200), newest first.","in":"query","name":"limit","required":false,"schema":{"default":null,"description":"Max contexts to return (default 50, cap 200), newest first.","format":"int64","type":["integer","null"]}},{"description":"Include deleted contexts (delete_context tombstones, readable for a\nweek after deletion) - that is where `bytes_deleted_at` confirms a\npurge actually removed the stored bytes. Default false.","in":"query","name":"include_deleted","required":false,"schema":{"default":null,"description":"Include deleted contexts (delete_context tombstones, readable for a\nweek after deletion) - that is where `bytes_deleted_at` confirms a\npurge actually removed the stored bytes. Default false.","type":["boolean","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List uploaded contexts (?limit=&include_deleted=)","tags":["contexts"],"x-capability":"list_contexts"},"post":{"description":"Reserve a presigned upload for large bytes (over write_file's 4 MiB, up to 10 GiB): a job build context, or any input that exists only in your sandbox (a prepared dataset, an eval set, a wheel you built) headed for a node. Returns a `context_id` plus either a single PUT url or multipart part urls; tar a folder (`tar -c . | zstd`), upload the bytes STRAIGHT to object storage with `curl -T` (never through MCP), call finalize_context, then submit_job with `context_id` - or get_context for a download url to curl onto a node. One finalized upload serves both. The urls point at the object store's own hostname (currently fly.storage.tigris.dev), NOT the API's: an egress allowlist that only permits the API host 403s the PUT at your own proxy - allow the storage host too. For builds, tar determinism is yours: sorted paths and fixed mtimes hit the cache; a sloppy re-tar merely misses it. `context_id` composes with an inline `context` (inline overlays the tar, inline wins), so upload gigabytes once and iterate on the Dockerfile inline.","operationId":"post_create_context","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"sha256":{"description":"Declared sha256 of the uploaded bytes, the cache identity: exactly\n64 lowercase hex chars, what `sha256sum` prints.","type":"string"},"size_bytes":{"description":"Declared size of the tar(.zst) to be uploaded (decoded bytes).","format":"int64","type":"integer"}},"required":["size_bytes","sha256"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Create an upload context for a job","tags":["contexts"],"x-capability":"create_context"}},"/preview/contexts/{id}":{"delete":{"description":"Delete an uploaded context: the stored bytes are removed and no download url is ever minted for it again. These are bytes YOU uploaded, in your own workspace - no other tenant's upload is reachable from here. Use this when an upload should not sit out its ~30-day lifecycle - the wrong folder, bytes you are not licensed to store with us, a session you are cleaning up. IRREVERSIBLE; re-uploading means create_context again. Refuses while a non-terminal job still needs the bytes (the refusal names the jobs - cancel_job them or let them finish). Idempotent: deleting twice succeeds. get_context then answers {status: \"deleted\", deleted_at} and gains `bytes_deleted_at` once the store confirms removal, so you can verify the purge rather than take our word for it. SCOPE, stated plainly: this deletes the uploaded context ONLY. Images already built from it are separate objects and are NOT deleted here (the registry has no delete verb today), job build/run logs and artifacts live out their own 30-day lifecycle, and the audit record of the upload and this deletion is retained.","operationId":"delete_delete_context","parameters":[{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","in":"path","name":"id","required":true,"schema":{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","type":"string"},"x-property":"context_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Delete an uploaded context (bytes removed; irreversible)","tags":["contexts"],"x-capability":"delete_context"},"get":{"description":"Status of an uploaded context plus, once finalized, a presigned download url - the import path for bytes that exist only in your sandbox (a prepared dataset, an eval set, a wheel): create_context → PUT → finalize_context → get_context, then land it on a node with one command - `run_command(node, \"curl -o ~/data.tar.zst ''\", detach: true)` for the big ones, `tar xf` if you tarred it - the node has the bandwidth and the disk; nothing rides through MCP. Returns {status: \"ready\", size_bytes, sha256, download: {url, expires_at}}; the url expires in minutes (this is a read: re-call for a fresh one), the object lives ~30 days unless you delete_context it sooner (which also answers here: {status: \"deleted\", deleted_at, bytes_deleted_at once the store confirms removal}). One finalized upload is reusable: curl it onto five nodes, build a job image from it - same object. While a big finalize runs you may see `{status: \"finalizing\"}` (or \"uploading\" from the other api instance) - keep polling until ready. `{status: \"failed\", error}` means the last finalize attempt died server-side: the uploaded parts are untouched - re-call finalize_context to retry. The download url points at the object store's own hostname (currently fly.storage.tigris.dev), NOT the API's - an egress allowlist needs that host too.","operationId":"get_get_context","parameters":[{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","in":"path","name":"id","required":true,"schema":{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","type":"string"},"x-property":"context_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Context status + a fresh download URL","tags":["contexts"],"x-capability":"get_context"}},"/preview/contexts/{id}/finalize":{"post":{"description":"Finalize an uploaded context (create_context): completes a multipart upload server-side (no ETag bookkeeping) and verifies the declared sha256 against the uploaded bytes. Small contexts answer `{status: \"ready\", size_bytes}` directly; a multi-GiB verify outlives your call - you get `{status: \"finalizing\"}` and the work continues server-side (your timeout never cancels it): poll get_context until status=ready. Re-calling while finalizing is safe (reports progress, never restarts). If the detached work fails, get_context reports `{status: \"failed\", error}` - re-calling finalize_context then starts a fresh attempt. A checksum mismatch is reported so you re-upload and resubmit. A no-op once ready. A finalized context feeds submit_job (`context_id`) and get_context (a download url to land it on a node), and stays reusable for ~30 days.","operationId":"post_finalize_context","parameters":[{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","in":"path","name":"id","required":true,"schema":{"description":"Context id from create_context (e.g. \"ctx-5rq8d\").","type":"string"},"x-property":"context_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Finalize an uploaded context","tags":["contexts"],"x-capability":"finalize_context"}},"/preview/evaluations":{"get":{"description":"Your evaluations, newest first.","operationId":"get_list_evaluations","parameters":[{"description":"The `limit` option.","in":"query","name":"limit","required":false,"schema":{"default":null,"format":"int64","type":["integer","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List evaluations","tags":["evaluations"],"x-capability":"list_evaluations"}},"/preview/evaluations/{name}":{"get":{"description":"One evaluation's counts by status, its judges, and whether it is final.","operationId":"get_get_evaluation","parameters":[{"description":"The evaluation's name.","in":"path","name":"name","required":true,"schema":{"description":"The evaluation's name.","type":"string"},"x-property":"evaluation"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"An evaluation's counts","tags":["evaluations"],"x-capability":"get_evaluation"}},"/preview/evaluations/{name}/real":{"post":{"description":"Supply real-world outcomes for an evaluation's report: rows of labels plus a number, joined to rollouts on the label keys each row carries. The report then adds Spearman rho between mean score and mean outcome per label group, with the join counts.","operationId":"post_submit_evaluation_real","parameters":[{"description":"The `evaluation` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"evaluation"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"rows":{"description":"Rows of {\"labels\": {...}, \"outcome\": number}, joined to rollouts on\nthe label keys each row carries.","items":true,"type":"array"}},"required":["rows"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Supply real-world outcomes for the report","tags":["evaluations"],"x-capability":"submit_evaluation_real"}},"/preview/evaluations/{name}/report":{"get":{"description":"The evaluation's report, computed server-side over the verdicts the ledger holds: counts, void rate, per-environment tables (optionally by a label key), integrity (single judge, judge bound to code, memo hits, environment-graded verdicts), and Spearman rho against real outcomes when supplied. Refuses to average rows graded under different judges (allow_mixed names the mix) and to compare label values that share an identity.","operationId":"get_get_evaluation_report","parameters":[{"description":"The `evaluation` this call acts on.","in":"path","name":"name","required":true,"schema":{"type":"string"},"x-property":"evaluation"},{"description":"Group the table by this label key (\"policy\").","in":"query","name":"by","required":false,"schema":{"default":null,"description":"Group the table by this label key (\"policy\").","type":["string","null"]}},{"description":"Allow rows graded under different judges (the report names the mix).","in":"query","name":"allow_mixed","required":false,"schema":{"default":null,"description":"Allow rows graded under different judges (the report names the mix).","type":["boolean","null"]}},{"description":"Allow a `by` key whose values share an identity.","in":"query","name":"allow_memo_across_labels","required":false,"schema":{"default":null,"description":"Allow a `by` key whose values share an identity.","type":["boolean","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The server-computed report (?by=&allow_mixed=)","tags":["evaluations"],"x-capability":"get_evaluation_report"}},"/preview/evaluations/{name}/rollouts":{"post":{"description":"Add rollouts to an OPEN evaluation (one submitted with open: true): the same parameters as submit_rollouts, attached to an existing set. An identity already in the evaluation is refused (an evaluation never holds two rows of one identity). Call seal_evaluation when the last batch is in.","operationId":"post_add_rollouts","parameters":[{"description":"The evaluation to attach to (created if new; refused if sealed or\nowned by another workspace).","in":"path","name":"name","required":true,"schema":{"default":null,"description":"The evaluation to attach to (created if new; refused if sealed or\nowned by another workspace).","type":["string","null"]},"x-property":"evaluation"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"$defs":{"EnvValue":{"anyOf":[{"description":"A literal value, passed to the process as-is.","type":"string"},{"description":"A stored org secret referenced by name; the platform resolves it\nat launch (create one: `gman secret create`; list: list_secrets).","properties":{"secret":{"description":"The secret's name (from list_secrets).","type":"string"}},"required":["secret"],"type":"object"}],"description":"One env value: a literal, or a stored-secret reference."}},"properties":{"chip":{"default":null,"description":"The runner's chip for a task-kind submit (\"h100\", \"cpu-2\"). Default:\nthe catalog container's, else h100. Ignored for sandbox kind.","type":["string","null"]},"command":{"default":null,"description":"The runner command (default: the image's). Task kind only.","type":["string","null"]},"egress":{"default":null,"description":"Egress for an openenv bake: \"open\" (default) or \"none\".","type":["string","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":{},"description":"Environment variables for the runner (a policy endpoint's key rides\nhere, sealed, and never reaches a sandbox). Task kind only.","type":"object"},"environment":{"description":"The environment: {\"kind\": \"task\"|\"sandbox\", \"env\": \"\"} or one\nstring - \"task:ghcr.io/acme/sim@sha256:...\", \"openenv:hub.openenv.dev/x/y@sha256:...\",\n\"sandbox:env-...\", or a catalog rollout container's name\n(\"mjx-rollout\"). Images are named at a DIGEST: the digest is the\nenvironment's identity and a tag can move. A sandbox env is the\nenv-... id create_sandbox_env returned."},"gpu":{"default":null,"description":"Alias of chip.","type":["string","null"]},"group":{"default":null,"description":"Attested group of N children from one state (sandbox kind: N forks of\nthe snapshot; requires --no-memo under eval). Seeds must number N.","format":"uint32","minimum":0,"type":["integer","null"]},"idempotency_key":{"default":null,"description":"Replay protection: the same key returns the first submit's evaluation\nrather than creating a second set.","type":["string","null"]},"judge":{"description":"The judge, pinned: \"goal-region@v1\", or \"swe-tests@sha256:\" to\nbind the label to code, or \"upstream:@\" for an\nenvironment's own reward. Reports never average rows whose judges\ndiffer.","type":"string"},"labels":{"default":null,"description":"Labels on every rollout ({\"policy\": \"ckpt41\"}): grouping for\nreports, never identity. Up to 16."},"lease_batch":{"default":null,"description":"Rollouts one lease hands the runner (default 32; up to 8192 for a\nvectorized simulator; openenv pools default 16, max 64 - each granted\nrollout forks a sandbox).","format":"int64","type":["integer","null"]},"max_duration_minutes":{"default":null,"description":"The runner attempt's max_duration_minutes (default 240). Task kind.","format":"int32","type":["integer","null"]},"memo":{"default":null,"description":"Memoization on/off (default follows the profile; true with \"train\" is\nrefused). A memo hit returns the stored verdict, unbilled.","type":["boolean","null"]},"mission":{"default":null,"description":"The mission this work rolls up into.","type":["string","null"]},"open":{"default":null,"description":"Leave the evaluation open so add_rollouts can append later.","type":["boolean","null"]},"policy":{"default":null,"description":"The policy label, part of the identity. REQUIRED for a sandbox-kind\neval submit with memoization on: the model driving the sandbox is\noutside the envelope, so without it the next checkpoint would be\nserved this one's verdicts. What we cannot see, we cannot tell apart.","type":["string","null"]},"profile":{"default":null,"description":"\"eval\" (default: memoization on, seeded-stochastic) or \"train\"\n(memoization off - a memoized training sample collapses your sample\ndiversity - and unrepeatable).","type":["string","null"]},"repro_class":{"default":null,"description":"\"bit-exact\", \"seeded-stochastic\" or \"unrepeatable\". Never defaults to\nbit-exact: we stamp the class you declare, and qualify_rollout is how\nyou find out whether it is true.","type":["string","null"]},"runners":{"default":null,"description":"Machines that may work the pool at once (default 4, max 32); started\nas the backlog warrants, so a ceiling on spend, not a reservation.","format":"int32","type":["integer","null"]},"seeds":{"default":null,"description":"Seeds: a list [0,1,2] or a range \"0..8\" / \"0..=7\". Default [0]."},"spec":{"default":null,"description":"One spec (the same as specs: [spec])."},"specs":{"default":[],"description":"The specs, one rollout per spec per seed. Each entry is an opaque JSON\nvalue handed to your environment verbatim (canonicalized, hashed, never\ninterpreted), or a manifest line {\"spec\": ..., \"labels\": {...},\n\"seed\": n} for per-spec labels.","items":true,"type":"array"},"state_expires_after":{"default":null,"description":"Expiry for states these rollouts declare (\"30d\", \"never\"). Default:\nthe org's snapshot default, else never.","type":["string","null"]}},"required":["environment","judge"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Add rollouts to an open evaluation","tags":["evaluations"],"x-capability":"add_rollouts"}},"/preview/evaluations/{name}/seal":{"post":{"description":"Seal an evaluation: no more rollouts join it. The report says final: true once every member is terminal.","operationId":"post_seal_evaluation","parameters":[{"description":"The evaluation's name.","in":"path","name":"name","required":true,"schema":{"description":"The evaluation's name.","type":"string"},"x-property":"evaluation"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Seal an evaluation","tags":["evaluations"],"x-capability":"seal_evaluation"}},"/preview/jobs":{"get":{"description":"List your jobs, newest first (org admins see the whole org's jobs; members see their own). `label` filters to one sweep. `summary: true` returns the rollup instead of rows: {total, by_state, failures_by_reason, oldest_queued_age_seconds, results} - `results` carries each terminal job's exit code and the JSON it wrote to $GMN_RESULT_PATH, so \"which of the 100 is best\" is this one call. A large queued count and a growing oldest_queued_age_seconds are not a reason to cancel or to stop submitting: a sustained backlog is what raises the fleet's procurement target for the shape, so the depth you are reading is what starts the machines that drain it (each queued job's queue.demand_note says it in full).","operationId":"get_list_jobs","parameters":[{"description":"Resume after this job id (the previous page's `next_cursor`) -\nkeyset pagination, newest first.","in":"query","name":"cursor","required":false,"schema":{"default":null,"description":"Resume after this job id (the previous page's `next_cursor`) -\nkeyset pagination, newest first.","type":["string","null"]}},{"description":"Max jobs to return (default 50, cap 200).","in":"query","name":"limit","required":false,"schema":{"default":null,"description":"Max jobs to return (default 50, cap 200).","format":"int64","type":["integer","null"]}},{"description":"Filter to one sweep's jobs by label (an indexed filter, GMAN-24).","in":"query","name":"label","required":false,"schema":{"default":null,"description":"Filter to one sweep's jobs by label (an indexed filter, GMAN-24).","type":["string","null"]}},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"summary":{"default":null,"description":"true = return the rollup instead of rows: {total, by_state,\nfailures_by_reason, oldest_queued_age_seconds, results} - \"which of\nthe 100 is best\" in one call.","type":["boolean","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List jobs (paged; ?label=)","tags":["jobs"],"x-capability":"list_jobs"},"post":{"description":"Submit an asynchronous job - a GPU shape, or the CPU-only \"cpu-8\" for CPU-bound batch stages (see `chip`): it builds your image (an inline `context` file map + Dockerfile, or a prebuilt `image` ref), queues fairly against your org's share, runs your `command`, and bills only the running attempt (builds bill after a monthly free allowance; queued and preempted time is free). Returns the job id, the rate, the cost ceiling, and once queued your position and wait estimate. The queue is built for long waits: hours queued is normal - the job holds its place for `queue_ttl_minutes` (default 3 days), so poll get_job minutes apart off `queue.estimated_wait_seconds`. Iterating on a script? Use a node instead (create_node + run_command): every submit builds and pushes a fresh image (~10 minutes even on a warm cache), so jobs suit unattended runs, not the edit-run-inspect loop. In the container, write your verdict as JSON to $GMN_RESULT_PATH and put files worth keeping in $GMN_OUTPUT_DIR - both come back on get_job when the attempt ends (the result inline, the output dir as a download URL). To land output in your OWN storage, pass `output_to: {connection, dest}` - a write-enabled connection and a prefix; no credential reaches your container. `depends_on: {job, require}` gates this job on another job's declared result: it never builds or places unless that job succeeds and the predicate holds, so a probe in front of an expensive arm costs nothing when it says no. Checkpoints: if $GMN_CHECKPOINT_DIR is non-empty at start, resume from it; write there and POST /v1/checkpoint - an interrupted attempt bills only to its last capture. resume: \"checkpoint\" also unlocks placement in shorter capacity windows, and a checkpointed job may POST /v1/yield to end its attempt and resume later. `idempotency_key` makes resubmission safe: the same key returns the same job. Give the job a mission (open_mission first): its cost and result roll up on the mission page you hand the human.","operationId":"post_submit_job","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"$defs":{"EnvValue":{"anyOf":[{"description":"A literal value, passed to the process as-is.","type":"string"},{"description":"A stored org secret referenced by name; the platform resolves it\nat launch (create one: `gman secret create`; list: list_secrets).","properties":{"secret":{"description":"The secret's name (from list_secrets).","type":"string"}},"required":["secret"],"type":"object"}],"description":"One env value: a literal, or a stored-secret reference."},"JobDependsOnParams":{"description":"A submit-time dependency (docs/designs/dependent-jobs.md): this job does\nnot build, does not queue and never places until a parent job has\nsucceeded and, optionally, a predicate over its declared result holds.","properties":{"allow_different_context":{"default":null,"description":"Run this job even though it is built from DIFFERENT code than the\nparent. Off by default, and the default is the point: \"the probe\nvalidated code the arm is not running\" is the failure this gate\nexists to prevent, so a parent built from another context is refused\nuntil you say you meant it.","type":["boolean","null"]},"job":{"description":"The parent job id (one of your org's jobs, from an earlier\nsubmit_job). It may still be building, queued or running - this job\nwaits for it.","type":"string"},"require":{"default":null,"description":"One comparison over the parent's DECLARED result - the JSON it wrote\nto $GMN_RESULT_PATH: `result` plus an optional dotted path, then ==,\n!=, <, <=, > or >=, then a literal (true, false, null, a number, or a\nquoted string). E.g. \"result.ok == true\", \"result.peak_gib < 72\".\nOmit to gate on the parent SUCCEEDING alone. The parent must succeed\neither way: a parent that crashed answers no question about this job.","type":["string","null"]}},"required":["job"],"type":"object"},"JobFileParam":{"description":"One inline context file (spec 548: the `context` map).","properties":{"base64":{"default":false,"description":"Set when `content` is base64 (binary files).","type":"boolean"},"content":{"description":"File contents (UTF-8, or base64 when `base64: true`).","type":"string"},"executable":{"default":false,"description":"Make the file executable (0755).","type":"boolean"}},"required":["content"],"type":"object"},"JobOutputToParams":{"description":"A job's declared output destination (docs/designs/dataset-ingress.md \"Jobs and\nconnections\"): the `GMN_OUTPUT_DIR` capture lands in one of your org's\nconnections instead of the platform artifacts bucket - the way a\ngeneration sweep's shards become a dataset where your tooling already\nreads, with no credential ever reaching the job.","properties":{"connection":{"description":"A write-enabled connection (list_connections). Kinds \"s3-keys\" and\nyour org's platform storage (\"gmn-storage\" - the auto-minted\nstorage/ connections): the PUT is presigned\ncontrol-plane-side, so no credential reaches your container; a\nstorage/ capture also commits into your org's storage\nledger (gman storage ls shows it; it counts against the storage\nquota and bills as stored bytes). A huggingface connection is\nrefused (the Hub has no presigned PUT - push to the Hub from a\nnode instead).","type":"string"},"dest":{"description":"The destination PREFIX (must end with \"/\"), inside the connection's\nscope pin. The capture lands at -.tar, so\nattempts and sweep variants can never collide. E.g.\n\"s3://acme-ml/synth/v3/\".","type":"string"}},"required":["connection","dest"],"type":"object"}},"properties":{"build_args":{"additionalProperties":{"type":"string"},"default":{},"description":"Docker build args (name → value).","type":"object"},"build_timeout_minutes":{"default":null,"description":"Max minutes the image BUILD may take before it is killed (default 30,\nceiling 120). Raise it for builds that legitimately need more runway -\na large dependency tree fetched from a slow or flaky upstream, heavy\nahead-of-time compilation. **This is one clock over the whole build,\nPUBLISHING INCLUDED:** fetching your context, your Dockerfile's steps,\nand then pushing the finished image to the registry, which for a large\nimage is minutes on its own. So a build whose steps finish near the\nceiling leaves the push no room and fails there every time, at the\nsame second, however often it retries - if you see \"publishing the\nbuilt image timed out\", the fix is this parameter (or a smaller\nimage), not a resubmit. Only metered build time is billed; queued and\nidle time never is, and a publish timeout is our plumbing and free.","format":"int32","type":["integer","null"]},"checks":{"default":null,"description":"The job's CHECKS: what this job must do, as configuration the\nplatform validates now and evaluates itself\n(docs/designs/job-checks.md; the full table is in the docs\nresource, and a job submitted without this gets it in the\nrefusal). REQUIRED on MCP. At least one phase:\n\n`{\"success\": {\"check\": }}` runs ONCE when the job stops.\nThe job reaches `succeeded` only if it passes; a failure lands\n`check_failed`, a verifier that could not RUN lands\n`check_errored`. Start here: it cannot stop a healthy job.\n\n`{\"health\": {\"check\": , \"interval_s\": 600,\n\"grace_period_s\": 900, \"fail_threshold\": 2, \"on_fail\": \"kill\"}}`\nruns while the job is live. `on_fail` is required: `record`,\n`kill` (snapshot the checkpoint slot, stop, close billing -\nterminal `self_terminated`), or `reschedule` (snapshot, stop,\nqueue again away from the failing host).\n\nA CheckSpec is `{\"type\": , ...}`, `{\"all_of\": [...]}` or\n`{\"any_of\": [...]}`. Built-ins: file_exists, file_grows,\nfile_size, jsonl_field, jsonl_rate, heartbeat, gpu_util,\ngemm_sane, http, tensor_changed, exec. The platform runs each from\nOUTSIDE your container, so nothing is installed in your image; use\n`exec` only where no built-in states your assertion (a command\nthat can only pass is refused).\n\nExample: `{\"success\": {\"check\": {\"type\": \"file_exists\", \"path\":\n\"/output/rows.jsonl\"}}}`. Liveness, one `touch()` per step:\n`{\"health\": {\"check\": {\"type\": \"heartbeat\", \"path\":\n\"/output/hb\"}, \"interval_s\": 600, \"on_fail\": \"kill\"}}`"},"chip":{"description":"Chip: \"h100\" (GPU), or a CPU-only size, \"cpu-2\" (2 reserved\ncores, 8 GiB RAM) or \"cpu-8\" (8 reserved NUMA-local cores,\n32 GiB RAM) - no GPU, at that size's CPU job rate. CPU jobs fit\nCPU-bound batch stages (dedup, filtering, tokenization,\ndecompress/convert, downloads) that would idle a GPU; cpu-2 is\nthe honest size for downloads and ingest, cpu-8 for parallel\nstages. Parallelism comes from submitting one job per shard\n(submit_jobs fans out a sweep), not from chip_count. Like all\njobs it may queue and be preempted; like the CPU nodes it may run\nfar from your GPU nodes, so move data with output_to, contexts, and\nobject storage, not by assuming a LAN. (Named for the accelerator,\nnot the vendor.)","type":"string"},"chip_count":{"default":null,"description":"Chips per attempt (1-8). Defaults to 1. GPU chips only - a CPU size\nis one reserved-core shape, so fan out jobs instead of counting chips.","format":"uint32","minimum":0,"type":["integer","null"]},"clock_lock":{"default":null,"description":"Benchmark mode: pin this attempt's GPUs to the model's published\nsustained clock for reproducible timings, instead of letting them\ndrift with boost/thermal state. Set once at submit and immutable for\nthe job's life (like the image). Physics, stated honestly: the lock is\na CEILING, not a guarantee (the hardware still throttles below it\nunder power/thermal pressure), and on an 8-GPU SXM baseboard neighbors'\nheat couples, so a full 8-GPU shape is the only fully isolated one.\nFree: no rate change (you pay in your own forgone boost headroom).\nDefault false. Use it for kernel/inference sweeps where noisy timings\nwould poison the comparison.","type":["boolean","null"]},"command":{"default":null,"description":"The command to run in the container (overrides the image's default).","type":["string","null"]},"context":{"additionalProperties":{"$ref":"#/$defs/JobFileParam"},"description":"Inline build context: a map of path → file. The image is built from\nthis. Mutually exclusive with `image`; composes with `context_id`\n(inline files overlay the uploaded tar, inline wins on collision).","type":"object"},"context_id":{"default":null,"description":"An uploaded large context from create_context. Mutually exclusive with `image`;\ncomposes with inline `context` (inline overlays it, inline wins).","type":["string","null"]},"depends_on":{"anyOf":[{"$ref":"#/$defs/JobDependsOnParams"},{"type":"null"}],"description":"Gate this job on another job: {job, require?}\n(docs/designs/dependent-jobs.md). Until the parent SUCCEEDS and\n`require` holds over the JSON it declared at $GMN_RESULT_PATH, this\njob does not build, does not queue and never places - so a cheap\nprobe can decide whether an expensive arm ever costs anything. If the\ngate closes, this job ends `canceled` with the reason, having spent\nnothing. The parent must be built from the same context as this job\nunless you pass allow_different_context."},"dockerfile_path":{"default":null,"description":"Dockerfile path within the context (default \"Dockerfile\").","type":["string","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":{},"description":"Environment variables (name → value). Names are echoed back; values\nare never returned. A value may reference a stored org secret by\nname - {\"secret\": \"wandb-prod\"} (list_secrets) - resolved fresh at\nevery attempt start, so it never appears in this chat and rotation\nreaches requeued attempts. Vended workspace tokens (per-tenant\ncredentials) cannot reference org secrets.","type":"object"},"force":{"default":null,"description":"Override a preflight BLOCK for this submission only\n(docs/designs/job-checks.md part 2). Today one check blocks: the\njob's worst-case cost against your remaining spend cap. Use it for a\njob you know will stop early - the block exists because the\nalternative is the cap stopping the same job mid-run, after the\nmoney is spent. Every override is recorded on the job and read as a\nreport about the check.","type":["boolean","null"]},"hf_cache":{"default":null,"description":"Mount your org's shared HuggingFace cache at HF_HUB_CACHE for every\nattempt: weights any of your org's jobs already pulled on the same\nmachine load from local disk instead of re-downloading into billed\ntime. Opt-in because the cache outlives the job - files written\nunder HF_HUB_CACHE stay for your org's later jobs (never another\norg's); a default job still leaves nothing behind. Best-effort by\ndesign: the cache is bounded per machine, may be cleared under disk\npressure, and when it fills the longest-unused models are evicted so\neach job starts with at least 32 GiB of room - a job that gets no\ncache just downloads as usual, though a single download larger than\nthat free room can still fill the cache mid-pull (submit unusually\nlarge models without the flag). Non-hub files parked there count\nagainst the same room, and a cache they fill past what evicting\nmodels can free is cleared whole and rebuilds cold. Refused together with an env named\nHF_HUB_CACHE (the platform sets that variable). Free: no rate\nchange. Default false.","type":["boolean","null"]},"idempotency_key":{"description":"Idempotency key: resubmitting with the same key returns the SAME job\n(never a duplicate). Reusing a key for a different request is refused.","type":"string"},"image":{"default":null,"description":"Use a prebuilt image by ref instead of building (e.g.\n\"nvcr.io/nvidia/pytorch:24.01-py3\"). Mutually exclusive with\n`context`/`context_id`. A PRIVATE image works too, with no\ncredential in this call: if an org admin stored a `registry`\nconnection whose scope covers this ref (list_connections), the\nplatform authenticates the pull itself. Otherwise the pull is\nanonymous, and a private ref fails with the registry's own\n\"pull access denied\" - the fix is a connection, never a token in\nthe ref.","type":["string","null"]},"label":{"default":null,"description":"A human-readable label shown in listings.","type":["string","null"]},"max_duration_minutes":{"default":null,"description":"Max run minutes before the job is stopped (default 60; the ceiling\nis a per-org limit, 720 by default - see list_limits).","format":"int32","type":["integer","null"]},"max_restarts":{"default":null,"description":"Provider-fault restarts allowed before failing (default 1, ceiling 3).\nPreemptions do NOT consume this.","format":"int32","type":["integer","null"]},"mission":{"default":null,"description":"The mission this job belongs to (open_mission first - it is\ncreate-or-attach, so re-opening a name resumes it): the\ninvestigation-level page that rolls up cost, results, and\nartifacts, and the link you hand the human. Name it for the\nquestion you are answering. Required: a call that omits it is\nrefused with the fix.","type":["string","null"]},"model":{"default":null,"description":"The model this job downloads, e.g. \"Qwen/Qwen3-VL-72B\" or\n\"Qwen/Qwen3-VL-72B@main\" (docs/designs/job-checks.md part 2).\nOptional: preflight otherwise reads the `--model` flag and the\n`from_pretrained` literals out of your command. Declaring it is\nwhat makes the disk check exact instead of heuristic - and when the\nmodel cannot be identified, the check stays silent rather than\nguessing.","type":["string","null"]},"no_preflight":{"default":null,"description":"Skip preflight entirely (the fast resubmit loop). Free either way.\nThe job record then says it skipped them, so a later postmortem\nknows which checks did not run.","type":["boolean","null"]},"output_to":{"anyOf":[{"$ref":"#/$defs/JobOutputToParams"},{"type":"null"}],"description":"Land the GMN_OUTPUT_DIR capture in one of your org's connections\ninstead of the platform artifacts bucket (docs/designs/dataset-ingress.md \"Jobs\nand connections\"). Omit to get the ordinary artifact download link."},"profiling":{"default":null,"description":"Benchmark mode's other half: unlock GPU profiler counters (CUPTI -\nwhat ncu needs) for the attempt. Whole-machine shapes only\n(chip_count: 8): GPU performance counters are a cross-tenant side\nchannel, so on a shared machine they are never for sale. The attempt\nplaces only on a profiling-capable machine (a small cohort - expect\nextra queue wait when it's busy). Free: no rate change (you pay in\nshape). Immutable at submit, like clock_lock - kernel-search jobs\ntypically set both. Default false. Unlike create_node, a job runs\nYOUR image, so bring your own profiler: it must ship nsight-compute\n2025 or newer, or ncu fails on current drivers with an opaque \"Failed\nto prepare kernel for profiling\" that no unlocked machine can fix.\nBasing on CUDA 12.9+ (or apt-installing cuda-nsight-compute) clears it.","type":["boolean","null"]},"queue_ttl_minutes":{"default":null,"description":"How long the job may wait in the queue before expiring (default 4320 =\n3 days).","format":"int32","type":["integer","null"]},"resume":{"default":null,"description":"Resumable placement: pass \"checkpoint\" to declare the command\nresume-aware - if $GMN_CHECKPOINT_DIR is non-empty at start, it\nresumes from it, and it checkpoints on its own cadence (write the\ndir, then POST /v1/checkpoint on the metadata service). The scheduler\nmay then start the job in shorter capacity windows: an allocation\nboundary becomes a planned stop-and-resume (never consuming\nmax_restarts), and a severed attempt bills only to its last\ncheckpoint. Any job with a committed capture may also POST\n/v1/yield to end its attempt and resume from the slot on demand\n(bills the full span - a restore, never a discount). Omit and the\njob runs as one attempt - unless a prior job in your org ran this\nexact image with this exact command and checkpointed, in which case\nit inherits \"checkpoint\" (get_job shows resume_source: \"inferred\"\nand the job it learned from). Pass \"none\" to refuse that inheritance.","type":["string","null"]},"task_lease_minutes":{"default":null,"description":"How long one leased task may run before the pool takes it back\n(default 15, max 120). Size it above your slowest unit, or renew with\nPOST /v1/tasks/{id}/extend.","format":"int32","type":["integer","null"]},"task_max_attempts":{"default":null,"description":"How many times one task may be leased before it is recorded failed\n(default 3). A failed task does not fail the job.","format":"int32","type":["integer","null"]},"task_max_runners":{"default":null,"description":"How many machines may work the set at once (default 4, max 32). We\nstart them as the backlog warrants and stop them as it drains, so this\nis a ceiling on spend, not a reservation: a set of 20 units never\nstarts 32 machines.","format":"int32","type":["integer","null"]},"tasks":{"default":null,"description":"A TASK SET: many units of work for ONE container, instead of one\njob doing one thing (docs/designs/task-sets.md). Each entry is an\nopaque JSON object handed back verbatim. Your command runs once per\nmachine and asks for work with\n`POST $GMN_METADATA_URL/v1/tasks/lease`, so one container start and\none image pull cover thousands of units, and losing a machine costs\nthe units in flight rather than the whole run. Write each unit's\noutput to the presigned `output_put_url` the lease hands you and\nreport done only once that PUT returns: a unit can run twice, so a\nshared output path is the one way to get a wrong answer here.","items":true,"type":["array","null"]},"tasks_open":{"default":null,"description":"Keep the task set OPEN so you can add_tasks as you go. The job keeps\nrunning while the set is open and finishes once you seal_tasks and the\npool drains. Omit for a set that is complete at submit.","type":["boolean","null"]}},"required":["chip","idempotency_key","mission"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Submit an async job","tags":["jobs"],"x-capability":"submit_job"}},"/preview/jobs/sweeps":{"post":{"description":"Submit a sweep: N variants of one job in a single call (1-256). `shared` carries everything submit_job accepts; each entry of `variants` overrides `command`, `env`, or `build_args` for its job (overrides replace the shared field wholesale). Put variant parameters in env: env and command are not in the build key, so an env/command-only sweep is ONE image build + N runs; overriding build_args builds a separate image per distinct combination. Every variant becomes an ordinary job - same validation, fairness, and billing as submit_job - sharing `label`, so list_jobs(label, summary: true) is the one-call rollup and each job's $GMN_RESULT_PATH verdict comes back in it. Validation is all-or-nothing: any invalid variant rejects the whole batch with the offenders named, and nothing is submitted. Variant i derives idempotency key \"{key}:{i}\", so resubmitting the same batch returns the same jobs. Cancel losers individually with cancel_job. Pass `shared.depends_on: {job, require}` to gate the WHOLE sweep on one earlier job's declared result: no variant builds, queues or places until it succeeds and the predicate holds, so one cheap probe can decide whether 256 expensive variants ever cost anything. Pass `shared.output_to: {connection, dest}` to land every variant's output under one connection prefix - each at -.tar, so a 256-shard generation sweep becomes one dataset in your own bucket with no key collisions and no credential in any container. SIZING: a sweep of many SHORT variants (minutes each) of one image is usually a TASK SET wearing sweep clothes - submit_job's `tasks` parameter runs the same units under ONE container start with per-unit retries and autoscaled runners; keep the sweep for variants that differ by build or run long.","operationId":"post_submit_jobs","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"$defs":{"EnvValue":{"anyOf":[{"description":"A literal value, passed to the process as-is.","type":"string"},{"description":"A stored org secret referenced by name; the platform resolves it\nat launch (create one: `gman secret create`; list: list_secrets).","properties":{"secret":{"description":"The secret's name (from list_secrets).","type":"string"}},"required":["secret"],"type":"object"}],"description":"One env value: a literal, or a stored-secret reference."},"JobDependsOnParams":{"description":"A submit-time dependency (docs/designs/dependent-jobs.md): this job does\nnot build, does not queue and never places until a parent job has\nsucceeded and, optionally, a predicate over its declared result holds.","properties":{"allow_different_context":{"default":null,"description":"Run this job even though it is built from DIFFERENT code than the\nparent. Off by default, and the default is the point: \"the probe\nvalidated code the arm is not running\" is the failure this gate\nexists to prevent, so a parent built from another context is refused\nuntil you say you meant it.","type":["boolean","null"]},"job":{"description":"The parent job id (one of your org's jobs, from an earlier\nsubmit_job). It may still be building, queued or running - this job\nwaits for it.","type":"string"},"require":{"default":null,"description":"One comparison over the parent's DECLARED result - the JSON it wrote\nto $GMN_RESULT_PATH: `result` plus an optional dotted path, then ==,\n!=, <, <=, > or >=, then a literal (true, false, null, a number, or a\nquoted string). E.g. \"result.ok == true\", \"result.peak_gib < 72\".\nOmit to gate on the parent SUCCEEDING alone. The parent must succeed\neither way: a parent that crashed answers no question about this job.","type":["string","null"]}},"required":["job"],"type":"object"},"JobFileParam":{"description":"One inline context file (spec 548: the `context` map).","properties":{"base64":{"default":false,"description":"Set when `content` is base64 (binary files).","type":"boolean"},"content":{"description":"File contents (UTF-8, or base64 when `base64: true`).","type":"string"},"executable":{"default":false,"description":"Make the file executable (0755).","type":"boolean"}},"required":["content"],"type":"object"},"JobOutputToParams":{"description":"A job's declared output destination (docs/designs/dataset-ingress.md \"Jobs and\nconnections\"): the `GMN_OUTPUT_DIR` capture lands in one of your org's\nconnections instead of the platform artifacts bucket - the way a\ngeneration sweep's shards become a dataset where your tooling already\nreads, with no credential ever reaching the job.","properties":{"connection":{"description":"A write-enabled connection (list_connections). Kinds \"s3-keys\" and\nyour org's platform storage (\"gmn-storage\" - the auto-minted\nstorage/ connections): the PUT is presigned\ncontrol-plane-side, so no credential reaches your container; a\nstorage/ capture also commits into your org's storage\nledger (gman storage ls shows it; it counts against the storage\nquota and bills as stored bytes). A huggingface connection is\nrefused (the Hub has no presigned PUT - push to the Hub from a\nnode instead).","type":"string"},"dest":{"description":"The destination PREFIX (must end with \"/\"), inside the connection's\nscope pin. The capture lands at -.tar, so\nattempts and sweep variants can never collide. E.g.\n\"s3://acme-ml/synth/v3/\".","type":"string"}},"required":["connection","dest"],"type":"object"},"SweepSharedParams":{"description":"The shared half of a sweep (GMAN-24): everything submit_job accepts,\nminus the per-call label/idempotency_key (those ride the sweep itself).","properties":{"build_args":{"additionalProperties":{"type":"string"},"default":{},"description":"Docker build args shared by every variant (a variant override\nreplaces these wholesale and builds a separate image).","type":"object"},"build_timeout_minutes":{"default":null,"description":"Max minutes each variant's image BUILD may take (default 30, ceiling\n120) - see submit_job's build_timeout_minutes.","format":"int32","type":["integer","null"]},"checks":{"default":null,"description":"The CHECKS every variant runs under (see submit_job's `checks`;\ndocs/designs/job-checks.md). REQUIRED on MCP, and shared by the\nwhole sweep rather than per-variant: the variants of one sweep are\nthe same job with different parameters, so one contract covers\nthem - and a 256-variant fan-out is precisely the shape where\nnobody is watching each unit."},"chip":{"description":"Chip: \"h100\" (GPU), or a CPU-only size, \"cpu-2\" or \"cpu-8\" (see\nsubmit_job's chip). A CPU sweep is the natural shape for\nembarrassingly parallel CPU-bound stages: one variant per shard,\nthe queue runs them as slots free up.","type":"string"},"chip_count":{"default":null,"description":"Chips per attempt (1-8). Defaults to 1. GPU chips only - a CPU size\nis one reserved-core shape; parallelism is more variants, not a count.","format":"uint32","minimum":0,"type":["integer","null"]},"clock_lock":{"default":null,"description":"Benchmark mode: pin every attempt's GPUs to the model's sustained\nclock - the right default for sweeps whose timings will be compared.","type":["boolean","null"]},"command":{"default":null,"description":"The command every variant runs unless it overrides one.","type":["string","null"]},"context":{"additionalProperties":{"$ref":"#/$defs/JobFileParam"},"description":"Inline build context (path → file), shared by every variant.\nMutually exclusive with `image`; composes with `context_id`.","type":"object"},"context_id":{"default":null,"description":"An uploaded large context from create_context, shared by every variant.","type":["string","null"]},"depends_on":{"anyOf":[{"$ref":"#/$defs/JobDependsOnParams"},{"type":"null"}],"description":"Gate the WHOLE sweep on another job: {job, require?}\n(docs/designs/dependent-jobs.md) - every variant waits, and none of\nthem builds, queues or places until the parent succeeds and `require`\nholds. One cheap probe in front of 256 expensive variants is the\nshape this is for. If the gate closes, every variant ends canceled\nhaving spent nothing."},"dockerfile_path":{"default":null,"description":"Dockerfile path within the context (default \"Dockerfile\").","type":["string","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":{},"description":"Env shared by every variant unless it overrides one (names echoed,\nvalues never returned). Values may reference stored org secrets:\n{\"secret\": \"wandb-prod\"} (list_secrets), resolved at every attempt\nstart. Vended workspace tokens (per-tenant credentials) cannot\nreference org secrets.","type":"object"},"force":{"default":null,"description":"Override a preflight block for this sweep (see submit_job's\n`force`). The check runs once, on the shared shape.","type":["boolean","null"]},"hf_cache":{"default":null,"description":"Mount your org's shared HuggingFace cache at HF_HUB_CACHE for every\nvariant - the right default for sweeps over one base model: the\nfirst job on each machine pays the download, the rest load from\nlocal disk instead of re-downloading into billed time. Best-effort\n(bounded per machine, may be cleared under disk pressure; a full\ncache evicts its longest-unused models to keep 32 GiB of room -\nnon-hub files count against that room too, and a cache they fill\npast what evicting models can free is cleared whole - and\na job without the cache downloads as usual). Refused together with\nan env named HF_HUB_CACHE (the platform sets that variable). Free.\nDefault false.","type":["boolean","null"]},"image":{"default":null,"description":"Use a prebuilt image by ref instead of building.","type":["string","null"]},"max_duration_minutes":{"default":null,"description":"Max run minutes per attempt (default 60; the ceiling is a per-org\nlimit, 720 by default - see list_limits).","format":"int32","type":["integer","null"]},"max_restarts":{"default":null,"description":"Provider-fault restarts allowed per job (default 1, ceiling 3).","format":"int32","type":["integer","null"]},"mission":{"default":null,"description":"The mission every variant belongs to (open_mission first - it is\ncreate-or-attach, so re-opening a name resumes it); the sweep's\nlabel nests inside it, so one mission can hold several sweeps.\nName it for the question you are answering. Required: a call that\nomits it is refused with the fix.","type":["string","null"]},"model":{"default":null,"description":"The model every variant downloads (see submit_job's `model`).","type":["string","null"]},"no_preflight":{"default":null,"description":"Skip preflight for this sweep (see submit_job's `no_preflight`).","type":["boolean","null"]},"output_to":{"anyOf":[{"$ref":"#/$defs/JobOutputToParams"},{"type":"null"}],"description":"Land every variant's GMN_OUTPUT_DIR capture under one connection\nprefix (docs/designs/dataset-ingress.md \"Jobs and connections\") - shared by the\nwhole sweep, never per-variant, because one destination prefix for N\nshards is the point: each lands at -.tar, so\n256 variants become one dataset with no collisions. Omit for the\nordinary per-job artifact links."},"profiling":{"default":null,"description":"Unlock GPU profiler counters (ncu) for every attempt - whole-machine\nshapes only (chip_count: 8); attempts place on the profiling-capable\ncohort. Free, immutable at submit. Your image must ship nsight-compute\n2025 or newer (CUDA 12.9+, or apt-install cuda-nsight-compute); below\nthat ncu fails on current drivers no matter which machine it lands on.","type":["boolean","null"]},"queue_ttl_minutes":{"default":null,"description":"Queue TTL per job (default 4320 = 3 days).","format":"int32","type":["integer","null"]},"resume":{"default":null,"description":"Resumable placement: pass \"checkpoint\" to declare the command\nresume-aware - if $GMN_CHECKPOINT_DIR is non-empty at start, it\nresumes from it, and it checkpoints on its own cadence (write the\ndir, then POST /v1/checkpoint on the metadata service). The scheduler\nmay then start the job in shorter capacity windows: an allocation\nboundary becomes a planned stop-and-resume (never consuming\nmax_restarts), and a severed attempt bills only to its last\ncheckpoint. Any job with a committed capture may also POST\n/v1/yield to end its attempt and resume from the slot on demand\n(bills the full span - a restore, never a discount). Omit and the\njob runs as one attempt - unless a prior job in your org ran this\nexact image with this exact command and checkpointed, in which case\nit inherits \"checkpoint\" (get_job shows resume_source: \"inferred\"\nand the job it learned from). Pass \"none\" to refuse that inheritance.","type":["string","null"]}},"required":["chip","mission"],"type":"object"},"SweepVariantParams":{"description":"One sweep variant (GMAN-24): overrides REPLACE the shared field wholesale.","properties":{"build_args":{"additionalProperties":{"type":"string"},"default":null,"description":"Override the shared build_args (replaces wholesale). Build args ARE\nin the build key, so this variant builds its own image.","type":["object","null"]},"command":{"default":null,"description":"Override the shared command for this variant.","type":["string","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":null,"description":"Override the shared env for this variant (replaces it wholesale) -\nthe right place for variant parameters: env is not in the build key,\nso an env-only sweep is one build + N runs. Values may reference\nstored org secrets: {\"secret\": \"wandb-prod\"}.","type":["object","null"]}},"type":"object"}},"properties":{"idempotency_key":{"description":"Idempotency key for the whole sweep: variant i derives \"{key}:{i}\",\nso resubmitting the same batch returns the same jobs.","type":"string"},"label":{"description":"The sweep's label - every job carries it, and\nlist_jobs(label, summary: true) is the one-call rollup.","type":"string"},"shared":{"$ref":"#/$defs/SweepSharedParams","description":"The job spec every variant shares."},"variants":{"description":"Per-variant overrides, one job each (1-256 variants).","items":{"$ref":"#/$defs/SweepVariantParams"},"type":"array"}},"required":["shared","variants","label","idempotency_key"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Submit a sweep: one build, N variants","tags":["jobs"],"x-capability":"submit_jobs"}},"/preview/jobs/validate":{"post":{"description":"Run PREFLIGHT and validate a job's CHECKS without submitting anything (docs/designs/job-checks.md). Free, about two seconds, and it changes nothing: use it in a loop while you get a job spec right, because it is faster and cheaper than a rejected submission per attempt. It answers the same three things submit_job would: does the `checks` block parse and mean something for this shape, does the job's worst-case cost fit the remaining spend cap (a BLOCK - the arithmetic is shown), and does the node's disk fit the model this job downloads (a WARNING). A check without sufficient data stays silent rather than guessing. Pass the same parameters you would pass to submit_job; the ones that only matter to a real run (context, image, idempotency_key, mission) are not needed.","operationId":"post_validate_job","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"$defs":{"EnvValue":{"anyOf":[{"description":"A literal value, passed to the process as-is.","type":"string"},{"description":"A stored org secret referenced by name; the platform resolves it\nat launch (create one: `gman secret create`; list: list_secrets).","properties":{"secret":{"description":"The secret's name (from list_secrets).","type":"string"}},"required":["secret"],"type":"object"}],"description":"One env value: a literal, or a stored-secret reference."}},"properties":{"checks":{"default":null,"description":"The checks block to validate (see submit_job's `checks`)."},"chip":{"description":"Chip: \"h100\", or a CPU size (\"cpu-2\", \"cpu-8\") - see submit_job.","type":"string"},"chip_count":{"default":null,"description":"Chips per attempt (1-8). Defaults to 1.","format":"uint32","minimum":0,"type":["integer","null"]},"command":{"default":null,"description":"The command the job would run - preflight reads a `--model` flag or\na `from_pretrained` literal out of it.","type":["string","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":{},"description":"Env the job would run with. Values are read only to identify a\nmodel reference; a stored-secret reference is never resolved here.","type":"object"},"max_duration_minutes":{"default":null,"description":"Max run minutes (default 60) - half of the worst-case arithmetic.","format":"int32","type":["integer","null"]},"model":{"default":null,"description":"The model the job downloads, e.g. \"Qwen/Qwen3-VL-72B@main\".","type":["string","null"]}},"required":["chip"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Preflight + validate a job's checks, without submitting","tags":["jobs"],"x-capability":"validate_job"}},"/preview/jobs/{id}":{"get":{"description":"Show one job by id: status, GPU, attempts, and while queued its position and a wait estimate (moves both ways under org fairness; null = no signal, not stuck; a forecast, never a countdown). Hours queued is normal (the spot holds for queue_ttl_minutes): pace polling minutes apart off the estimate; failure reason and exit code arrive once terminal. While building, `build` carries live progress (phase, byte/layer counts, updated_at): multi-GB images legitimately download for minutes, `updated_at` advancing means it is moving, and byte counts hold still past `fetching` by design - read the phase, and stream: \"build\" for what the build is doing. While starting, `startup` is the same shape for the run's own image pull (absent fields = no signal yet, never stalled). Mid-run telemetry (`checkpoint_capture`, `preview` - the one replaceable peek at a $GMN_OUTPUT_DIR path - and `samples`), declared from inside the container, is documented in the agent docs (the gman://docs/llms.txt resource). A completed attempt carries `result` (the $GMN_RESULT_PATH JSON, verbatim; result_error names the failure) and `artifact` (the $GMN_OUTPUT_DIR capture, a presigned download on the object store hostname, currently fly.storage.tigris.dev - an egress allowlist must permit it; a severed attempt uploads nothing); with `output_to` declared it instead carries `output: {connection, uri}` - the bytes land in your own store. Pass `stream` (\"build\" or \"run\") for incremental logs (`offset` to advance, `tail: true` for the last 4 KiB, `attempt` for an earlier attempt). A run-log slice answers the poll question: `attempt_state` is \"not_started\" (no run log YET - keep polling the JOB), \"live\", \"complete\", or \"never_ran\" (never got a container, NO log ever - an empty slice is final), and `eof: true` means stop looping; an unreadable range is named in `note` and skipped at `next_offset`, never silently spliced. Logs live 30 days; status checks never touch a worker. The poll target after submit_job.","operationId":"get_get_job","parameters":[{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","in":"path","name":"id","required":true,"schema":{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","type":"string"},"x-property":"job_id"},{"description":"Which log stream to include: \"build\" or \"run\" (omit for status only).","in":"query","name":"stream","required":false,"schema":{"default":null,"description":"Which log stream to include: \"build\" or \"run\" (omit for status only).","type":["string","null"]}},{"description":"Read logs from this byte offset (incremental polling).","in":"query","name":"offset","required":false,"schema":{"default":null,"description":"Read logs from this byte offset (incremental polling).","format":"int64","type":["integer","null"]}},{"description":"Return only the last 4 KiB (\"what's it doing right now\").","in":"query","name":"tail","required":false,"schema":{"default":null,"description":"Return only the last 4 KiB (\"what's it doing right now\").","type":["boolean","null"]}},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"attempt":{"default":null,"description":"Which run attempt's log to read (1-based: attempt 1 is the first\nrun; default: the current attempt). Earlier attempts' logs survive\na preemption/restart - pass attempt: 1 to read what the first run\nprinted after a rerun began.","format":"int32","type":["integer","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Job status + logs (?stream=&offset=&tail=)","tags":["jobs"],"x-capability":"get_job"}},"/preview/jobs/{id}/cancel":{"post":{"description":"Cancel a job. SCOPE: one of your own batch jobs in your own workspace - never end-user data, another tenant, or a production system. Stopping a run whose answer you already have, or one that is clearly failing, is the routine and expected call: it stops the meter, and the job's record and logs stay readable through get_job (logs live 30 days). Returns immediately with status `canceling`; a running attempt is stopped (and billed up to the stop), a queued or building job stops for free. Cancelling a task set's job stops every machine working the set. Idempotent: canceling an already-finished job is a no-op. Cancel because you no longer want the RESULT - never because the queue is deep: queued time is free, and a sustained backlog for a shape is what raises the fleet's procurement target for it, so cancelling withdraws the demand that was starting the machines that would have drained the queue. The wait gets longer, not shorter. To stop paying attention rather than stop the work, leave it queued (it holds its place for queue_ttl_minutes) and poll get_job on a relaxed cadence.","operationId":"post_cancel_job","parameters":[{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","in":"path","name":"id","required":true,"schema":{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","type":"string"},"x-property":"job_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Cancel a job","tags":["jobs"],"x-capability":"cancel_job"}},"/preview/jobs/{id}/tasks":{"post":{"description":"Add tasks to an OPEN task set (one submitted with `tasks_open: true`). The job keeps running while the set is open, so you can start the work before you know every unit. Up to 5,000 tasks per call and 50,000 per set. Appending to a SEALED set is refused: sealing promises the pool will drain, and the job may already have finished on that promise. Call seal_tasks when the last batch is in.","operationId":"post_add_tasks","parameters":[{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","in":"path","name":"id","required":true,"schema":{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","type":"string"},"x-property":"job_id"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"tasks":{"description":"The units to append. Each is an opaque JSON object handed back to your\nrunner verbatim.","items":true,"type":"array"}},"required":["tasks"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Add tasks to an open task set","tags":["jobs"],"x-capability":"add_tasks"}},"/preview/jobs/{id}/tasks/seal":{"post":{"description":"Close an open task set: no more tasks are coming. The job finishes once the remaining tasks drain. Until you call this, a runner that finds the pool empty waits for more instead of exiting, so an unsealed set runs (and bills) until its max_duration. Idempotent.","operationId":"post_seal_tasks","parameters":[{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","in":"path","name":"id","required":true,"schema":{"description":"Job id from submit_job (e.g. \"job-8x2mf\").","type":"string"},"x-property":"job_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Close a task set: no more tasks","tags":["jobs"],"x-capability":"seal_tasks"}},"/preview/limits":{"get":{"description":"Your effective limits, every knob in one read - the numbers the teaching errors quote, available before the wall instead of at it. Each row carries the effective value for you in this org, the layer that decided it (\"default\", or an \"org override\"/\"customer override\" set by support - overrides can lower a limit as well as raise it), whether support can set it per-org today (settable: true), and one line on what it bounds. A row's hard_max, when present, is the platform hard cap no override can exceed (fleet hardware, not policy). Rows with layer \"platform\" are platform-set job, build, and checkpoint knobs: deploy configuration, not per-org levers today.","operationId":"get_list_limits","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"org":{"default":null,"description":"Organization: an org uuid or an org name from list_team's\nmemberships; omitted = your active org.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Your effective limits, each with the deciding layer","tags":["limits"],"x-capability":"list_limits"}},"/preview/logs/queries":{"post":{"description":"Your logs, one call instead of a run_command tail loop: every detached command's AND every job run's stdout/stderr ships here as produced, labeled by mission and run (block buffering and stopped nodes stop mattering - logs outlive nodes and disks). Filter by mission / run (a job-/cmd-/ses- id) / node / text substring for the common case, or pass full LogQL. Returns time-ordered lines, newest kept when the limit cuts (truncated:true) - narrow the range or filter rather than paging.","operationId":"post_query_logs","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end":{"default":null,"description":"Range end, RFC3339 (default: now).","type":["string","null"]},"limit":{"default":null,"description":"Max lines returned, newest kept (default 100, cap 1000).","format":"uint32","minimum":0,"type":["integer","null"]},"mission":{"default":null,"description":"Filter: mission name (composes {mission=\"...\"}).","type":["string","null"]},"node":{"default":null,"description":"Filter: node name (composes {node=\"...\"}).","type":["string","null"]},"query":{"default":null,"description":"Full LogQL (optional - the filter params below compose the query\nfor the common case). `$mission`/`$run` substitute the params.","type":["string","null"]},"run":{"default":null,"description":"Filter: one run - a job-/cmd-/ses- scope id (composes {run=\"...\"}).","type":["string","null"]},"start":{"default":null,"description":"Range start, RFC3339 (default: one hour before `end`).","type":["string","null"]},"text":{"default":null,"description":"Filter: plain-text substring the line must contain (|= \"...\").","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Search logs (LogQL, or the filter params)","tags":["logs"],"x-capability":"query_logs"}},"/preview/metrics/queries":{"post":{"description":"PromQL over your org's metrics: platform telemetry, free and automatic - GPU (gmn_gpu_utilization, gmn_gpu_memory_used_bytes, gmn_gpu_power_watts, gmn_gpu_temperature_celsius), system per container (gmn_cpu_seconds_total, gmn_memory_used_bytes, gmn_memory_limit_bytes, gmn_network_receive_bytes_total, gmn_network_transmit_bytes_total), and spend (gmn_node_spend_usd, gmn_org_mtd_spend_usd) - labeled {node, mission} on nodes and {run, mission} on jobs, plus everything your registered scrapes collect. Range query; results are bounded and downsampled (at most 20 series x 200 points, truncated:true when cut) - ask narrower questions rather than paging. $mission/$run in the query substitute the matching params.","operationId":"post_query_metrics","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"end":{"default":null,"description":"Range end, RFC3339 (default: now).","type":["string","null"]},"mission":{"default":null,"description":"Substituted for `$mission` in the query.","type":["string","null"]},"query":{"description":"PromQL. `$mission` and `$run` substitute the params below, e.g.\nsum(rate(vllm:generation_tokens_total{mission=\"$mission\"}[5m])).","type":"string"},"run":{"default":null,"description":"Substituted for `$run` in the query (a job-/cmd-/ses- scope id).","type":["string","null"]},"start":{"default":null,"description":"Range start, RFC3339 (default: one hour before `end`).","type":["string","null"]},"step_seconds":{"default":null,"description":"Step seconds (default: the range divided into ~200 points).","format":"uint32","minimum":0,"type":["integer","null"]}},"required":["query"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Range-query metrics (PromQL)","tags":["metrics"],"x-capability":"query_metrics"}},"/preview/missions":{"get":{"description":"Your workspace's missions, newest first: name, title, cost to date, last activity, finished. active_only:true narrows to missions with live work. get_mission(name) is the full receipt.","operationId":"get_list_missions","parameters":[{"description":"Only missions with live activity (an open command, a job still\nqueued/building/running).","in":"query","name":"active_only","required":false,"schema":{"default":null,"description":"Only missions with live activity (an open command, a job still\nqueued/building/running).","type":["boolean","null"]}},{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","type":"string"}},{"description":"Max rows (default 50, ceiling 200), newest first.","in":"query","name":"limit","required":false,"schema":{"default":null,"description":"Max rows (default 50, ceiling 200), newest first.","format":"int64","type":["integer","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List missions (paged)","tags":["missions"],"x-capability":"list_missions"},"post":{"description":"Open (create or attach) a mission: the investigation-level grouping over nodes, jobs, commands, and artifacts, with an org-unique human-readable name. Use one per question you are answering (\"serve llama-70b under $X\"), and open it FIRST - before the first create_node or submit_job - then pass mission: \"\" on create_node / run_command / submit_job / submit_jobs / export_file: their work and cost roll up on the mission's page and get_mission, telemetry arrives labeled by mission (query_metrics / query_logs / search_traces), starter charts draw automatically, and save_chart adds the views worth keeping. The response's url is the human's window on the work - hand it over early, not with the final report. The page is org-private (sign-in, workspace visibility): the url discloses nothing outside the org. Create-or-attach by name: reconnecting (or a fleet of parallel agents) reuses the same name and lands in the same mission. Names are permanent org-wide handles - pick a meaningful one. Missions are optional and never required; they never cap or gate anything (workspaces are policy; missions are reporting). Declare the verdict with finish_mission when the question is answered. If the org cannot start paid work right now (no payment method on file, payment past due, suspended), the response carries a `warning` naming the blocker - surface it to the human WITH the url, so they fix billing before watching an empty page.","operationId":"post_open_mission","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"default":null,"description":"Mission name: lowercase letters, digits, '-' (1-63 chars), unique in\nyour organization and PERMANENT (missions are never deleted or\nrenamed). Pick a meaningful one - it is the receipt's handle, the\nURL, and the invoice line. An existing name attaches instead of\ncreating (create-or-attach): reconnecting agents and parallel\nsessions share one mission by using one name. Omitted =\nauto-generated.","type":["string","null"]},"title":{"default":null,"description":"One-line human description, shown beside the name on the mission\npage. Ignored when attaching to an existing mission.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Open (create or attach) a mission","tags":["missions"],"x-capability":"open_mission"}},"/preview/missions/{name}":{"get":{"description":"The mission's receipt, one call: cost so far (node time, job runs, builds; accruing:true while anything is still live), the nodes it touched with each one's cost share, the jobs rollup (states, failures, per-terminal declared results - sweeps nest by label), artifacts, the samples count (the timeline itself is list_samples), and the declared verdict. Also the cheap way for a fresh session to re-orient: \"what have I done so far\" is this one call, not N list_* calls.","operationId":"get_get_mission","parameters":[{"description":"Mission name (from open_mission / list_missions).","in":"path","name":"name","required":true,"schema":{"description":"Mission name (from open_mission / list_missions).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The mission's receipt: cost, nodes, jobs, verdict","tags":["missions"],"x-capability":"get_mission"}},"/preview/missions/{name}/charts":{"post":{"description":"Save (or update) a chart on a mission's page - design the view the human should see: told to train a model, save the loss chart in the same breath as open_mission. Spec is small versioned JSON: {v: 1, title, viz: line|area|stat|bars, unit?, window?, queries: [{signal: \"metrics\", query: , legend?}]} (1-4 queries, 32 KiB cap). One chart per mission is the default (default: true moves it; the first saved chart starts as it). Charts group into dashboards: pass dashboard: to place a chart (\"main\" if omitted) - naming a new dashboard creates it, and the page's Charts tab shows one dashboard at a time with a picker. Charts and dashboards are views, not records - freely updated and deleted.","operationId":"post_save_chart","parameters":[{"description":"Mission name (from open_mission / list_missions).","in":"path","name":"name","required":true,"schema":{"description":"Mission name (from open_mission / list_missions).","type":"string"},"x-property":"mission"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"dashboard":{"default":null,"description":"Dashboard to place the chart on (lowercase letters, digits, '-';\ndefault \"main\"). Dashboards are named groups of charts - the\nmission page's Charts tab shows one at a time. Naming a new\ndashboard creates it; re-saving a chart moves it; a dashboard\nwhose last chart is deleted disappears.","type":["string","null"]},"default":{"default":null,"description":"Make this the mission's default chart (the one its page opens on).\nThe first chart saved is the default automatically.","type":["boolean","null"]},"name":{"description":"Chart name: lowercase letters, digits, '-' (unique per mission).","type":"string"},"spec":{"additionalProperties":true,"description":"The chart document, v1: {v: 1, title, viz: line|area|stat|bars,\nunit?, window?, queries: [{signal: \"metrics\", query, legend?}]},\n1-4 queries, <=32 KiB. Pass the JSON object itself; a JSON-encoded\nstring of the object is also accepted.","type":"object"}},"required":["name","spec"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Save (or move) a chart on a mission's dashboard","tags":["missions"],"x-capability":"save_chart"}},"/preview/missions/{name}/charts/{chart}":{"delete":{"description":"Delete a chart from your mission's page. Charts are views, not records: the metrics behind one stay queryable and save_chart re-adds it, so dropping a view that stopped being useful loses nothing. Deleting the default promotes the oldest remaining chart.","operationId":"delete_delete_chart","parameters":[{"description":"Mission name.","in":"path","name":"name","required":true,"schema":{"description":"Mission name.","type":"string"},"x-property":"mission"},{"description":"Chart name (from get_mission's charts list).","in":"path","name":"chart","required":true,"schema":{"description":"Chart name (from get_mission's charts list).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Delete a chart from a mission's dashboard","tags":["missions"],"x-capability":"delete_chart"}},"/preview/missions/{name}/finish":{"post":{"description":"Declare a mission's verdict and mark it finished: pass the conclusion a human (or a future, context-fresh agent) needs as `result` JSON - the winning config, the numbers compared, the artifact to download. Finish is a declaration, never a gate: later work still attaches, and re-finishing overwrites the verdict (last write wins). The verdict renders on the mission's page and returns verbatim on get_mission.","operationId":"post_finish_mission","parameters":[{"description":"Mission name (from open_mission / list_missions).","in":"path","name":"name","required":true,"schema":{"description":"Mission name (from open_mission / list_missions).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"result":{"default":null,"description":"The investigation's verdict, as JSON (up to 32 KiB): the numbers a\nhuman compares - the winning config, the throughput, the artifact\nid. Returned verbatim by get_mission and rendered on the mission\npage. Re-finishing overwrites it (last write wins)."}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Declare the mission's verdict","tags":["missions"],"x-capability":"finish_mission"}},"/preview/missions/{name}/updates":{"get":{"description":"A mission's updates, newest first: what the agents working it have said about it, with each body's markdown as posted. The cheap way for a fresh session to re-orient on the PLOT rather than the numbers - get_mission says what it cost, this says what was tried, ruled out, and found. Pass `at: \"upd-...\"` to fetch the page containing one specific update, or `before` to page further back.","operationId":"get_list_updates","parameters":[{"description":"The mission whose updates to read (from open_mission).","in":"path","name":"name","required":true,"schema":{"description":"The mission whose updates to read (from open_mission).","type":"string"},"x-property":"name"},{"description":"How many, newest first. Default 50, max 200.","in":"query","name":"limit","required":false,"schema":{"default":null,"description":"How many, newest first. Default 50, max 200.","format":"int64","type":["integer","null"]}},{"description":"Page further back: the `posted_at` of the oldest row you already\nhave, RFC 3339.","in":"query","name":"before","required":false,"schema":{"default":null,"description":"Page further back: the `posted_at` of the oldest row you already\nhave, RFC 3339.","type":["string","null"]}},{"description":"Fetch the page containing this specific update (`upd-...`), rather\nthan the newest page. What makes a permalink an agent handed to a\nhuman still resolve after hundreds more updates.","in":"query","name":"at","required":false,"schema":{"default":null,"description":"Fetch the page containing this specific update (`upd-...`), rather\nthan the newest page. What makes a permalink an agent handed to a\nhuman still resolve after hundreds more updates.","type":["string","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"A mission's updates, newest first (?limit=&before=&at=)","tags":["missions"],"x-capability":"list_updates"},"post":{"description":"Post an update to a mission: a short title and an optional markdown body, shown as the mission's front page for the human watching. The page is org-private (sign-in, workspace visibility): posting results or job ids here is not public disclosure. Post when something a human would want to know changed - you started a sweep, you ruled something out, you found the answer, you are stuck - not on a timer. To show a picture or a clip, export the file with export_file and write ![what it shows](art-...) in the body: the artifact id is replaced with a public share link (the one public thing an update mints; unshare revokes) and the image or video plays on the page. Use kind: \"alert\" only when a person needs to act. Updates cannot be edited or deleted, so post a correction as a new update. Returns {update_id, url, body, embeds, warnings} - the url is a permalink worth handing to a human, and the body reads back with the artifact ids already substituted.","operationId":"post_post_update","parameters":[{"description":"The mission this update is about (from open_mission). An update is\nABOUT a mission, so unlike the create verbs there is no\nunattributed case and no dated catch-all.","in":"path","name":"name","required":true,"schema":{"description":"The mission this update is about (from open_mission). An update is\nABOUT a mission, so unlike the create verbs there is no\nunattributed case and no dated catch-all.","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"body":{"default":null,"description":"The detail, as markdown. Paragraphs, ## headings, bold, italic,\n`code`, fenced code blocks, lists, quotes, links, and pipe tables\nrender; anything else shows as its own literal text. Write\n![what it shows](art-...) to put an exported image, video, or\naudio clip inline - the artifact id becomes a public share link\n(unshare revokes it). A\nmarker inside a code fence stays literal and publishes nothing.","type":["string","null"]},"kind":{"default":null,"description":"\"note\" (the default) or \"alert\". Use \"alert\" only when a person\nneeds to act - you are blocked, or you found something that\nchanges what they want. It is the one signal the platform cannot\nderive on its own, so spending it on progress makes it useless.","type":["string","null"]},"title":{"description":"The headline: one line, plain text, up to 200 characters. What\nchanged, in the words a human would use - \"Run 7 is the best LoRA\nso far\", not \"update 4\".","type":"string"}},"required":["title"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Post a mission update (title, markdown body, kind)","tags":["missions"],"x-capability":"post_update"}},"/preview/networks":{"get":{"description":"Your workspace's private networks: each with its name, id, address prefixes, and member roster (node name, that node's stable mesh addresses, its dns_name `.givemeanode.internal` - resolvable from inside member containers - and, while placed, its region/zone). Stopped members still appear - membership and addresses survive stop/wake; a stopped member just drops traffic until something wakes it (mesh traffic never does - a wake is always an explicit command).","operationId":"get_list_networks","parameters":[{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The workspace's private networks with member rosters","tags":["networks"],"x-capability":"list_networks"},"post":{"description":"Create a private network: a workspace-scoped mesh that nodes join (attach_network, or create_node's `network` parameter) to reach each other directly over stable private addresses. Private by default in every direction: a node that never attaches keeps exactly today's isolation, members-only membership, no cross-network routing, no internet transit, and nothing on the mesh is ever reachable from the public internet (expose_port stays the only public door). INSIDE a network the posture is one trust zone: every port a member listens on is reachable by every other member - joining a network is trusting its members. Idempotent per name: creating an existing name returns it (`created: false`), never a duplicate; omitted name = auto-generated. Each member gets a stable IPv4 (from 100.64/10) and IPv6 (ULA) for the node's whole life - across stop/wake, recreate, and repair - plus a DNS name: from inside a member container, `.givemeanode.internal` (and the short node name, via the search domain) resolves to a peer's stable addresses, and the metadata service's /v1/network returns the full roster in one curl. Outside the containers, peers are reached by the addresses get_node/list_networks show.","operationId":"post_create_network","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"default":null,"description":"Network name (the node-name grammar: lowercase letters, digits,\n'-'; 1-63 chars), unique in your workspace. Omitted =\nauto-generated. Creating an existing name returns it (idempotent\nper name).","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Create a private network (idempotent per name)","tags":["networks"],"x-capability":"create_network"}},"/preview/networks/{name}":{"delete":{"description":"Delete a private network, freeing its name and address block. SCOPE: one virtual network of your own workspace - the nodes themselves keep running, and create_network mints another any time. Refuses while ANY member rows exist: detach every node first (detach_network - detach is explicit, never a side effect of delete), and each detached address then sits in a 7-day quarantine that still counts as a member row - so a network becomes deletable at the earliest 7 days after its last detach (stale peers must drain before its addresses can ever mean someone else).","operationId":"delete_delete_network","parameters":[{"description":"Network name (from `list_networks`).","in":"path","name":"name","required":true,"schema":{"description":"Network name (from `list_networks`).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Delete an empty private network (refuses while members exist)","tags":["networks"],"x-capability":"delete_network"}},"/preview/nodes":{"get":{"description":"List the nodes in your workspace (GPU and CPU shapes): name, chip, state, and - while placed on a region-labeled machine - the region it runs in (absent = not placed or not reported; CPU nodes may run far from your GPU nodes, so check it before assuming a LAN). A private-network member also shows its network with stable mesh addresses, DNS name, and region/zone. Work on a node with run_command; poll a pending node with get_node. THESE ARE NOT ALL YOUR NODES: a workspace is shared, and other agents in other sessions - plus every human member - create nodes here too. Each row carries `yours`, `created_by`, and the `mission` it was created for, plus `sessions` and `running_commands` when work is live on it; a `shared` block counts what is not yours. PASS mission: \"\": `yours` is an ACCOUNT fact, and the several agents one person runs at once share that account, so without it a node from your own other investigation reads as yours. With it, every row gains `same_mission` - work only where that is true. Create your own node rather than borrowing one: reusing a node overwrites its files and environment, and stopping or deleting it destroys work you did not start.","operationId":"get_list_nodes","parameters":[{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","type":"string"}},{"description":"Rows per page. Clamped to the range shown.","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Rows per page. Clamped to the range shown.","maximum":200,"minimum":1,"type":"integer"}},{"description":"The mission you are working under (from open_mission). Naming it\nmarks each row with `same_mission`, and is the only way to tell\nyour own OTHER agents' nodes from this one's: a request resolves\nto your ACCOUNT, and parallel agents on one login share it.","in":"query","name":"mission","required":false,"schema":{"default":null,"description":"The mission you are working under (from open_mission). Naming it\nmarks each row with `same_mission`, and is the only way to tell\nyour own OTHER agents' nodes from this one's: a request resolves\nto your ACCOUNT, and parallel agents on one login share it.","type":["string","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List nodes (paged)","tags":["nodes"],"x-capability":"list_nodes"},"post":{"description":"Create a node - one of the named node types, \"h100-1\", \"h100-8\", \"cpu-2\", or \"cpu-8\" (see the chip parameter). Never blocks: returns status \"provisioning\" (capacity was free; the response carries the locked per-minute rate) or status \"queued\" with a live position and wait estimates (the scheduler provisions your node the moment a slot frees, so poll get_node rather than re-creating, pacing off estimated_ready_seconds_p90, the measured time until RUNNING; null means no recent history, not a long wait). Re-calling with the same name while queued or provisioning is idempotent, never a duplicate - and an explicit max_wait on a queued re-call extends the hold, forward-only (a shorter re-ask never cuts it). Billing starts when the node is ready: rate.node_per_min is what the whole node costs per minute (rate.per_min is per-GPU), and a ready node with no session idles on its billed grace window - rate.minimum_minutes (currently 15 min on 1x, 20 min on 8x) - then auto-stops. That clock starts at provision time, so poll get_node comfortably inside the window and land a run_command to keep the node; call stop_node the moment you are done. To keep it awake across several turns of work, call hold_node rather than parking a sleep loop. clock_lock (benchmark mode) and profiling (GPU profiler counters) are free and immutable once set - see those parameters; network: \"\" joins a private network at creation (see attach_network for the trust model). NAME IT SO IT IS OBVIOUSLY YOURS: the workspace is shared with other agents, a generic name (\"train\", \"gpu\") collides, and a name held by someone else's node refuses rather than handing you their box. Give the node a mission: open_mission first, pass mission: \"\" here, and its provenance, work, and cost land on the mission's page - the link you hand the human. Omitting it files the node in the workspace's dated catch-all; work on the node afterward inherits its mission, so naming it once is enough.","operationId":"post_create_node","parameters":[{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"chip":{"description":"Chip: the node type's name. \"h100-1\" is one GPU and \"h100-8\" is\na full 8-GPU node; both also answer to their original spellings,\n\"h100\" and \"8xh100\", which is what responses echo.\n\"cpu-2\" and \"cpu-8\" are the CPU-only shapes,\neach billed as one unit and never given a GPU. \"cpu-2\" (2\nreserved physical cores, 8 GiB RAM) fits downloads, ingest, and\npreprocessing whose output you hand to a GPU node - either by\nsnapshotting this node and restoring onto the GPU shape, or through\norg storage (export_data, then import_data) when you want the data\nreusable. That work is bounded by the origin and the disk, so\ntwo cores are the honest size. \"cpu-8\" (8 reserved physical\ncores on one NUMA node, low inter-core latency INSIDE the node,\n32 GiB RAM) fits parallel CPU work. A CPU shape promises\nNOTHING about proximity to GPU capacity: it may be placed far\nfrom your GPU nodes - in a different region - so move data with\norg storage and contexts, not by assuming a LAN (a shared private\nnetwork reaches it; the mesh promises reachability, never\nlatency). clock_lock/profiling are GPU features and refuse on\nCPU shapes.","type":"string"},"clock_lock":{"default":null,"description":"Benchmark mode: pin this node's GPUs to the model's published\nsustained clock for reproducible timings, instead of letting them\ndrift with boost/thermal state. Set once at creation and immutable\nfor the node's life (like the image). Physics, stated honestly: the\nlock is a CEILING, not a guarantee (the hardware still throttles\nbelow it under power/thermal pressure), and on an 8-GPU SXM baseboard\nneighbors' heat couples, so a full 8x node is the only fully isolated\nshape. Free: no rate change (you pay in your own forgone boost\nheadroom). Default false. Use it for kernel/inference sweeps where\nnoisy timings would poison the comparison.","type":["boolean","null"]},"from_snapshot":{"default":null,"description":"The fork (spec \"Volume snapshots\"): a ready snapshot id (snap-...,\nfrom snapshot_node / list_snapshots). The new node provisions with\nits volume RESTORED from the snapshot instead of empty - prepare an\nenvironment once, snapshot it, fan out clones. Unless you name an\nimage, the node runs the snapshot's own image (the one its source\nnode ran), so venvs and compiled extensions resume on the toolchain\nthey were built under; naming a different image warns rather than\nrefuses. Restore is provisioning: clones are free until ready\n(attach: \"restoring\"). Each clone's volume gets its own fresh key;\nthe snapshot stays reusable until delete_snapshot. A snapshot holds\nthe volume only, never /scratch: a restored node's /scratch (when\ndeclared) starts empty, so plan to re-download scratch data before\nresuming. A restore CAN cross the CPU/GPU boundary in either\ndirection - a snapshot taken on a CPU shape restores onto a GPU\nshape and the reverse - so an ingest done on cpu-2 can be handed to\na GPU node as a snapshot. (org storage, export_data then\nimport_data, still works and is the better move when you want the\ndata reusable rather than a single node's disk.)","type":["string","null"]},"home":{"default":null,"description":"Registry-ref images only: the ABSOLUTE path your persistent disk\nmounts at - the one path that survives stops and wakes (everything\nelse is the image, reset every wake). Omitted = the image's own\nWORKDIR when it names a usable absolute path, else /root. Pick the\ndirectory your image works out of (\"/root\", \"/workspace\"). Refused\nalongside a catalog image, whose contract is /home/dev.","type":["string","null"]},"image":{"default":null,"description":"Catalog image name, or YOUR OWN container image as a registry ref\n(\"nvcr.io/nvidia/pytorch:24.01-py3\", \"ubuntu:24.04\" - anything\nwith a '/', ':' or '@digest' is a ref; bare words are catalog\nnames). Omitted = the catalog default - except with\n`from_snapshot`, where omitted = the SNAPSHOT'S own image, so a\nrestore resumes on the toolchain the volume was built under; and\nwith `profiling: true`, where omitted = the catalog's profiling\nentry. Naming a catalog image that can't profile alongside\n`profiling: true` is refused, never silently substituted; naming\none that differs from a snapshot's image warns (venvs and compiled\nextensions may not import across images). An unknown catalog name\nis refused with the current list and a one-line description of\neach - pick by the toolkit your wheels were built against. The\ndefault is a bare CUDA toolkit that ships NO torch, so PyTorch\nwork should name a pytorch-* entry, whose torch is preinstalled\nand built for its toolkit. CUDA version selection IS image\nselection, and the choice is immutable for the node's life. A\nregistry ref runs YOUR image under the platform's supervision: a\ntag resolves ONCE at create to a manifest digest and every start\nruns exactly that build (a moved tag never moves your node); the\nplatform supplies the entrypoint (your image's own never runs);\nyour persistent disk mounts at `home` (below), and ONLY that path\nsurvives stops; run_command needs /bin/sh in the image; a private\nref pulls through the org `registry` connection whose scope pin\nadmits it. Never scanned - it runs in the same hardened isolation\nevery node gets. Profiling with your own image works only if it\nships nsight-compute >= 2025. The catalog stays the recommended\npath: pre-pulled on every host (instant starts), CUDA contract\nCI-gated, contents public.","type":["string","null"]},"max_wait":{"default":null,"description":"How long a queued node may hold its spot with nobody using it: a\nduration like \"30m\" (ceiling \"12h\"; default: the server queue cap).\nRe-calling with a longer max_wait extends an existing hold,\nforward-only - a multi-hour wait should be one hold, not a polling\nloop.","type":["string","null"]},"mission":{"default":null,"description":"The mission this node belongs to (open_mission first - it is\ncreate-or-attach, so re-opening a name resumes it). Name it for\nthe question you are answering (\"serve-llama-70b\"), never for the\nmachine: this is the page a human opens to see what the work cost\nand what it concluded. Work you run on the node inherits it, so\nthis is usually the only place you say it. Required: a call that\nomits it is refused with the fix.","type":["string","null"]},"name":{"default":null,"description":"Node name (lowercase letters, digits, '-'); omitted = auto-generated.","type":["string","null"]},"network":{"default":null,"description":"Join a private network at creation: a network name in your\nworkspace - one that doesn't exist yet is created for you (the\ncreate is audited separately; same as create_network then\nattach_network). Membership gives the node stable private\naddresses for its whole life and makes every port it listens on\nreachable by every other member - one trust zone: joining a\nnetwork is trusting its members. Omit = no network (exactly\ntoday's isolation; the mesh is opt-in per node).","type":["string","null"]},"profiling":{"default":null,"description":"Benchmark mode's other half: unlock GPU profiler counters (CUPTI -\nwhat ncu needs) for this node. Whole-machine node types only (chip\n\"h100-8\"): GPU performance counters are a cross-tenant side channel,\nso on a shared machine they are never for sale - on a machine that is\nentirely yours they can only tell you about yourself. Placement waits\nfor a profiling-capable machine (a small cohort; the queue states it\nhonestly). Free: no rate change (you pay in shape). Set once at\ncreation and immutable, like clock_lock - kernel-search customers\ntypically set both. Default false. Also picks your image: an\nunlocked machine is only half of profiling - the image has to carry\na profiler that works (nsight-compute 2025+) - so omitting `image`\nlands you on the catalog's profiling entry, which may or may not be\nthe plain default depending on what the default currently ships.","type":["boolean","null"]},"scratch_gib":{"default":null,"description":"Ephemeral scratch disk, GiB: mounts fast local disk at /scratch,\nDESTROYED at stop and never snapshotted - put caches and\nre-downloadable data there (streaming-dataset shards, HF caches,\ndecompressed archives), never the only copy of anything. Free: you\npay only node time, and the space is claimed up front so it cannot\nvanish mid-run. Set once at creation and immutable, like clock_lock.\nDefault 0 (no scratch). Your ceiling is the node_scratch_gib limit;\nthe platform hard cap is 550 GiB (list_limits shows both) - no\nraise exceeds the cap. Large values narrow placement to workers\nwith the disk free right now - the refusal names the numbers.","format":"uint64","minimum":0,"type":["integer","null"]}},"required":["chip","mission"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Create a node (never blocks: provisioning or queued)","tags":["nodes"],"x-capability":"create_node"}},"/preview/nodes/{name}":{"delete":{"description":"Destroy a node's disk permanently and free its name. SCOPE: one rented node inside your own workspace, and nothing else - no end-user data, no other tenant, no production system is reachable from this tool, and no other node, snapshot, or artifact is touched. Retiring a node you are finished with is the routine, expected end of a session: it frees the name and stops the disk billing, so make the call yourself once the work is off the box. Deletion is a crypto-erase: irreversible, files do NOT survive - snapshot_node first if you might want them later. Queued, stopped, lost, and still-provisioning creates can be deleted (a stuck create cancels immediately; nothing is billed while provisioning): stop_node first if it's running (the two-step is deliberate). To merely stop paying while keeping files, use stop_node instead. Deleting a node this investigation did not create refuses unless you pass force: true - there is nothing to hand back after a crypto-erase. Pass mission: \"\" so that check can see your OWN other agents too: without it the platform can only tell accounts apart, and your parallel agents share one. One deletion is worth a second thought: a QUEUED node deleted because the wait looks long. Its GPUs are a term in the fleet's demand target, so that entry is what STARTS the machine it is waiting for - queued time is free, and the queued answer's demand_note says it in full.","operationId":"delete_delete_node","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"force":{"default":null,"description":"Destroy a node somebody else created. Without it, a node whose\n`created_by` is not you refuses. Deletion is a crypto-erase of\ntheir disk: irreversible, and nothing you can hand back.","type":["boolean","null"]},"mission":{"default":null,"description":"The mission you are working under (from open_mission). Naming it\nis how the platform tells your agent apart from your OTHER agents:\na request resolves to your ACCOUNT, and parallel agents on one\nlogin share it, so without this a node from your other\ninvestigation reads as \"yours\". With it, a node created under a\ndifferent mission is treated exactly like a teammate's.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"503":{"$ref":"#/components/responses/Settling"}},"summary":"Delete a stopped node (crypto-erase, irreversible)","tags":["nodes"],"x-capability":"delete_node"},"get":{"description":"Show one node by name: status, image, the effective rate, the region it runs in, and, while queued or provisioning, the queue position and wait estimates (estimated_wait_seconds; estimated_ready_seconds and its p90 until RUNNING - pace polling off the p90; null = no history, not a long wait; your place is held either way). This is the poll target: poll until running, then run_command. While placed, `resources` is the container's cgroup budget (cpu_limit, memory_limit_bytes) - size parallelism and memory to those, not to os.cpu_count()/free, which report the HOST - and `environment` the CUDA-compile facts (image_nvcc, image_torch, driver_version, cuda_major_max, compute_capability) - node_doctor checks the pairing. `gpu_memory` is per-GPU used/free VRAM: read free_mib_min before co-locating work. A network member shows `network` (mesh addresses, dns_name, region/zone). A ready node with no session reports \"running (idle)\" plus idle_stops_at - the moment it auto-stops unless a run_command lands first; hold_node keeps it awake across turns (a live hold shows as `hold`). A silent host (execs failing \"host isn't responding\") shows as `host` {responding: false, silent_seconds}; absent = it answers. Status checks never wake a stopped node. A stopped node carries `stopped` {reason, at, note, ran_seconds - the billed session length} plus wake_estimate: what a wake requested right now would be quoted (queued_wakes plus ready estimates; a reading, never a reservation; assumes_contested prices the contested case). durable_as_of is the newest instant of the disk replicated off its machine. When the machine under a node is retiring, this call carries machine_retires_at and machine_retirement_note - hours ahead, for a stopped node's parked disk too, so poll for it on any long unattended run. A failed create answers status \"failed\" with the real error for about an hour; re-creating the name starts fresh. A shell can poll GET /preview/nodes/{name} (docs' HTTP API section).","operationId":"get_get_node","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"mission":{"default":null,"description":"The mission you are working under (from open_mission): the answer\ngains `same_mission`, the only signal that separates this agent\nfrom your OTHER agents, which share your account.","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"One node: state, rate, queue position","tags":["nodes"],"x-capability":"get_node"}},"/preview/nodes/{name}/commands":{"get":{"description":"List a node's detached commands, newest first: {command_id, state, env (names only), started_at, ended_at?, exit_code?, result?, note?}. A `lost` row's `note` says that no exit status was recorded and whether the node's disk is still there; get_command carries the full disclosure. `result` is each command's declared verdict ($GMN_RESULT_PATH), so comparing runs is this one call. The listing is the newest 100 (a note says when older history was clipped; get_command still reads any command by id). These are the commands started with run_command(detach:true), the ones that can still be interrogated with get_command. Command lines are NOT echoed back (they're recorded encrypted, as an operator-visible debugging record, and shown to your own org on the mission page's Commands tab - unless your organization's retention policy declines the capture, see get_retention); track what a command_id is from your own run_command call; env values are never echoed anywhere, names only. Works against stopped nodes and never wakes one.","operationId":"get_list_commands","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","in":"query","name":"cursor","required":false,"schema":{"description":"Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.","type":"string"}},{"description":"Rows per page. Clamped to the range shown.","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Rows per page. Clamped to the range shown.","maximum":200,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"List commands on a node (paged)","tags":["nodes"],"x-capability":"list_commands"},"post":{"description":"Run a shell command on a node. Synchronous (default): returns {exit_code, stdout, stderr, truncated}, budgeted by `timeout` (default and ceiling 60s here; nothing streams mid-call, and the HTTP door honors up to 300s). At the deadline the command is killed and the error carries the captured tail - only as good as your flushing (stdout is block-buffered off-tty: python -u / PYTHONUNBUFFERED=1); anything longer belongs in detach:true, whose log survives. Detached: returns {command_id, log_path} immediately; poll get_command for output and the exit code, kill_command to stop it. restart:\"on-failure\" respawns a detached command on nonzero exit (backoff, same log, then crash_loop; the node bills throughout). Write your verdict as JSON to $GMN_RESULT_PATH (injected) and it comes back on the status call - small structured results beat log parsing. SECRETS GO IN env, NEVER THE COMMAND STRING: command lines are recorded (unless your org's retention policy declines it - see get_retention), env values ride only to the process (never recorded, names-only echo, redacted from logs); use short-lived, minimally scoped tokens and treat them as burned. Write files with the write_file tool. The tmux contract: files under ~ survive stop_node and wake; processes don't - a detached command dies with the container (it ends `lost`, no exit_code, no result; its log file survives) - let a needed verdict reach an exit_code on get_command first. Push results out from inside the node (s3 cp, git push) before stopping. Calling this on a stopped node wakes it (billing starts when it's ready): you may get status \"queued\" (poll get_node, then re-call) or \"waking\" (re-call shortly). NEVER a sleep keepalive: \"keep this node awake while I work across turns\" is hold_node - same node time, no command slot, no fake work on your mission page. The work lands on the node's mission automatically; pass mission: \"\" only to attribute it somewhere else (reusing a node under a new investigation).","operationId":"post_run_command","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"$defs":{"EnvValue":{"anyOf":[{"description":"A literal value, passed to the process as-is.","type":"string"},{"description":"A stored org secret referenced by name; the platform resolves it\nat launch (create one: `gman secret create`; list: list_secrets).","properties":{"secret":{"description":"The secret's name (from list_secrets).","type":"string"}},"required":["secret"],"type":"object"}],"description":"One env value: a literal, or a stored-secret reference."}},"properties":{"command":{"description":"The shell command, run by `sh -c` in the node's container as the\n`dev` user. Command lines are RECORDED (encrypted at\nrest, operator-visible as the debugging record): never put secrets\nhere; pass them as `env`. Files are written with write_file.","type":"string"},"detach":{"default":null,"description":"true = detached: returns {command_id, log_path} immediately and the\ncommand keeps running on the node (poll get_command; kill_command\nstops it). Anything longer than the timeout ceiling belongs here.","type":["boolean","null"]},"env":{"additionalProperties":{"$ref":"#/$defs/EnvValue"},"default":{},"description":"Environment variables for the command (name → value), THE way to\nhand the node a secret (an HF token, a presigned URL). Values ride\nonly to the process: never recorded, never echoed back (names only\nfrom get_command/list_commands), redacted from logs. Use\nshort-lived, minimally scoped tokens and treat them as burned after\nthe task. A value may also reference a stored org secret by name -\n{\"secret\": \"wandb-prod\"} (list_secrets) - resolved at launch so the\nvalue never appears in this chat; the process still sees the plain\nvalue, so burned-class care still applies. Vended workspace tokens\n(per-tenant credentials) cannot reference org secrets.","type":"object"},"hold_on_failure_minutes":{"default":null,"description":"Minutes to hold the node awake if this DETACHED command FAILS - a\nnonzero exit, a signal death, or a restart budget exhausting into\ncrash_loop. The moment a run fails is the moment its inputs are\nmost valuable, because the retry needs exactly what the failed\nattempt had on disk, and by default a failure starts the idle timer\nlike any other ending: the node stops and /scratch is destroyed\nwhile you are asleep. This keeps it alive so you can look. A clean\nexit is unaffected. The node bills for the hold; ceilinged by\nnode_hold_ceiling_hours, and release_node ends it early.","format":"uint32","minimum":0,"type":["integer","null"]},"max_duration_minutes":{"default":null,"description":"REQUIRED with on_wake: how long the boot command may run before it\nis killed. A boot command whose node arrived at 3am and wedged bills\nuntil someone notices, so the bound is not optional and there is no\ndefault that would pick a number for you. Ceiling:\nboot_command_max_duration_ceiling_minutes (list_limits). At expiry\nthe command is killed and the node returns to its normal grace\nwindow.","format":"uint32","minimum":0,"type":["integer","null"]},"max_restarts":{"default":null,"description":"Restart budget for restart:\"on-failure\" (default 20). When it\nexhausts, the command ends as crash_loop - bounded burn by design.","format":"uint32","minimum":0,"type":["integer","null"]},"max_wait":{"default":null,"description":"How long a wake this command triggers may hold its place in the\nqueue when capacity is busy (duration like \"30m\"; default 1h;\nceiling 12h). The call itself still returns by `timeout` - the hold\noutlives it, and get_node polls the queue. **Size this to the wait,\nnot to your patience:** the queued answer carries\nestimated_ready_seconds, and if the default hold is shorter than\nthat estimate the response says so in hold_note - a lapsed hold\nmeans the node never arrives at all. Re-calling create_node with the\nnode's name and a max_wait extends a queued hold (forward-only).","type":["string","null"]},"mission":{"default":null,"description":"Attribute this command's work (and the node time it opens) to a\nmission (from open_mission): the investigation-level grouping whose\npage rolls up cost, results, and artifacts, and whose Commands tab\nshows this command line to your org (one more reason secrets ride\nenv, never the command string). Node time reaches a mission's\nreceipt through the commands that carry mission:, not through\ncreate_node. Omit and this work joins the node's own mission,\nwhich is usually what you want - pass it only to attribute the\nwork somewhere else, as when you reuse a node for a new\ninvestigation.","type":["string","null"]},"on_wake":{"default":null,"description":"true = register this as the node's BOOT COMMAND instead of running\nit now: the node must be stopped or queued, and the command starts\nthe instant the node reaches ready, before the idle-grace clock can\nmatter. The command_id comes back immediately and get_command\nanswers for it (state \"pending_wake\") from that moment, so your next\ntick reads a command row rather than re-running a race. Requires\nmax_duration_minutes. One per node: registering another replaces it\nand the response says which. Refused on a running node - drop\non_wake to run the command now. This is how an agent that is not\nawake at the moment a node arrives still gets work started on it.","type":["boolean","null"]},"restart":{"default":null,"description":"Restart policy for a DETACHED command: \"never\" (default) or\n\"on-failure\" - the worker respawns the process when it exits\nnonzero (exponential backoff, same log with a marker line per\nattempt, restart count on get_command). Exit 0 ends the command;\nkill_command always ends it. Bounded by max_restarts: when the\nbudget exhausts the command ends as crash_loop and the node idles\ninto grace as usual. The node keeps billing the whole time.","type":["string","null"]},"timeout":{"default":null,"description":"Whole-call budget in seconds (default 60; ceiling 60 on this MCP\nconnection - your client enforces its own per-call deadline,\ncommonly 60s, so a longer budget could never be delivered here;\nthe HTTP API door honors up to 300). Covers the wake when the node\nis stopped, then the command; at the deadline the command is\nkilled. With detach:true it budgets only the wake; the command\nitself runs unbounded.","format":"uint64","minimum":0,"type":["integer","null"]}},"required":["command"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"503":{"$ref":"#/components/responses/Settling"}},"summary":"Run a command (sync, or detach:true)","tags":["nodes"],"x-capability":"run_command"}},"/preview/nodes/{name}/commands/{id}":{"get":{"description":"Status + incremental output of a detached command: {status, exit_code?, output, next_offset, truncated, result?, note?}. `result` is the JSON the command left at $GMN_RESULT_PATH, verbatim (result_error names the honest failure: invalid JSON, or over 32 KiB). `output` is bytes of the log from `offset` (default 0); pass `next_offset` back verbatim to stream; truncated:true means more is available right now. Status checks NEVER wake a stopped node: while the node is stopped only the final tail captured at exit is served - a read below the tail start returns empty output with next_offset jumped forward and a note naming the gap (the full log survives on the disk; wake the node to read it all). Polling this does not keep the node awake or reset its idle grace. A supervised command (restart:\"on-failure\") also reports {restart, max_restarts, restarts, last_exit} - flapping is visible here without reading logs; status \"crash_loop\" means the restart budget exhausted on a nonzero exit. `oom_kills` (with a note) means the kernel's OOM killer fired in the node's container during the run - a bare \"Killed\" in the log plus exit 137 is the container's memory ceiling, not a bug in your script; get_node's `resources` carries the budget. Status \"lost\" means no exit status was ever recorded - the container went away before the exit reached us (a stop, a cap stop, a crash, an OOM kill), so there is no exit_code and no result; `note` says what survived (the volume's files and the log, unless the node was lost with its host). A run whose verdict you need must reach an exit_code here BEFORE you stop the node. A command that NEVER STARTED (an on_wake boot command whose launch failed or lapsed) has no log at all: `output` is the reason it never ran, and there is no exit_code because nothing ever exited.","operationId":"get_get_command","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"description":"The cmd-... id returned by run_command(detach:true) (or list_commands).","in":"path","name":"id","required":true,"schema":{"description":"The cmd-... id returned by run_command(detach:true) (or list_commands).","type":"string"},"x-property":"command_id"},{"description":"Byte offset to read from (default 0). Pass the previous response's\nnext_offset back verbatim to stream incrementally.","in":"query","name":"offset","required":false,"schema":{"default":null,"description":"Byte offset to read from (default 0). Pass the previous response's\nnext_offset back verbatim to stream incrementally.","format":"uint64","minimum":0,"type":["integer","null"]}},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Command status + log (offset-polling)","tags":["nodes"],"x-capability":"get_command"}},"/preview/nodes/{name}/commands/{id}/kill":{"post":{"description":"Kill a detached command: TERM to its whole process group, then KILL after 10s. SCOPE: one process group inside your own node's container - the node, its files, its other commands, and everything outside that container keep running. Ending a run you are no longer waiting on is routine and the cheap direction: it bills node time until it exits. Idempotent: killing a command that already finished returns its current state, never an error. The log keeps everything written so far; get_command shows the final state and exit code.","operationId":"post_kill_command","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"description":"The cmd-... id returned by run_command(detach:true) (or list_commands).","in":"path","name":"id","required":true,"schema":{"description":"The cmd-... id returned by run_command(detach:true) (or list_commands).","type":"string"},"x-property":"command_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Kill a detached command","tags":["nodes"],"x-capability":"kill_command"}},"/preview/nodes/{name}/copies":{"post":{"description":"Copy a file or directory from one of your nodes to another - the one-verb node-to-node move (docs: no mesh or shared network required; it works between any two RUNNING nodes of your workspace, across hosts and regions). The bytes ride one storage hop, exercised entirely by the platform's hosts: the source side is an export (a directory tars its contents; the artifact receipt - id, size, sha256 - shows on the mission page, ~30 days), the destination side an import - the bytes appear at dst_path owned by dev, and no URL or credential ever enters either container, nothing rides through this chat. A FILE lands at dst_path exactly (parents created; a trailing \"/\" means \"into this directory under the source's name\"). A DIRECTORY's CONTENTS land extracted under dst_path, merged file-by-file over what's already there - a re-copy after edits overwrites per file instead of failing on an existing tree. The call waits for the export leg (returning artifact_id, size_bytes, sha256) and starts the import leg: poll get_import(dst_node, import_id) until \"complete\". Both nodes must be RUNNING - a stopped end is a refusal, never a wake (run_command anything to wake it, then re-call); a same-node copy is refused (run_command a plain cp there - it never leaves the disk). Copy time is node time on both ends, and the import leg holds the destination out of grace while it streams. Bounded by the artifact export rate and size caps and the import caps (refusals name the numbers). Every call is recorded to your org's audit log (both nodes, both paths, the artifact id - never bytes).","operationId":"post_copy_file","parameters":[{"description":"Source node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Source node name (from `list_nodes`).","type":"string"},"x-property":"src_node"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"dst_node":{"description":"Destination node name (must differ from src_node).","type":"string"},"dst_path":{"description":"Where it lands on dst_node, absolute or ~-relative. Copying a FILE:\nthis is the destination file path (parents created; a trailing \"/\"\nmeans \"into this directory under the source's name\", the cp\nconvention). Copying a DIRECTORY: this is the destination\ndirectory; the source directory's CONTENTS land under it.","type":"string"},"mission":{"default":null,"description":"Attribute the copy (and its artifact receipt) to a mission (from\nopen_mission). Omit and it joins the source node's own mission,\nwhich is usually what you want.","type":["string","null"]},"src_path":{"description":"The path to copy FROM, absolute or ~-relative (e.g. \"~/prep/app\").\nA regular file or a directory.","type":"string"}},"required":["src_path","dst_node","dst_path"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Copy a file/dir from this node to another node","tags":["nodes"],"x-capability":"copy_file"}},"/preview/nodes/{name}/data-exports":{"post":{"description":"Push a file or directory from a RUNNING node to your own storage through a stored org connection with the \"write\" verb (list_connections shows verbs): the platform exercises the access on the host - never in this chat, never inside the node. `dest` must sit inside the connection's scope. S3 family (kind \"s3-keys\"): dest is an object key (e.g. \"s3://acme-ml/results/run7/model.tar\") and lands as ONE object (a directory is tarred; extract with tar -xf). Your org's own storage (auto-minted storage/, kind \"gmn-storage\"): dest is an object key like s3, OR a '/'-terminated PREFIX - a directory then lands as a mirrored TREE of objects, one per file, committed as they land (get_export shows files_done/files_total). The connection names the bucket, so a dest here may be bucket-relative or full: \"corpus-v3/\" = \"s3://datasets/corpus-v3/\". Tree re-runs RESUME: objects already landed with matching size are skipped, never re-sent. Landed bytes count against your storage quota and bill as stored bytes. Hugging Face (kind \"huggingface\"): dest is \"owner/name[@revision][:path/in/repo]\" (e.g. \"acme/ckpts@main:runs/run7/\"; \"datasets/owner/name\" for dataset repos) and a directory lands as individual files under the path in ONE commit - model checkpoints stay loadable, never a tar; the repo must already exist on the Hub. Returns {export_id} immediately; poll get_export(node, export_id). A stopped node is a refusal, never a wake. Export time is node time: you're billed while it streams, and the transfer holds the node out of grace. Size is bounded (the refusal names the numbers; s3 and platform-storage exports STREAM as multipart, so big checkpoints fit - the Hub arm bounds any single FILE at one PUT, so shard big checkpoints or push them to s3; tree members too are single-PUT bounded). Every call is recorded to your org's audit log (connection, node, source, dest - never any credential). For a download link instead of a push, use export_file.","operationId":"post_export_data","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"connection":{"description":"Connection name (from `list_connections`; needs the \"write\" verb).","type":"string"},"dest":{"description":"The destination, inside the connection's scope: an object key for\ns3 kinds (e.g. \"s3://acme-ml/results/run7/model.tar\"), or\n\"owner/name[@revision][:path/in/repo]\" for huggingface (e.g.\n\"acme/ckpts@main:runs/run7/\").","type":"string"},"mission":{"default":null,"description":"Attribute this work to a mission (from open_mission). Omit and it\njoins the node's own mission, which is usually what you want.","type":["string","null"]},"source":{"description":"Path in the node's volume, absolute or ~-relative (e.g.\n\"~/out/model\"). To an s3 dest a directory exports as ONE tar\nobject and a file streams as-is; to a huggingface dest a\ndirectory lands as individual files (one commit) and a file as\none file.","type":"string"}},"required":["connection","source","dest"],"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Push a file or directory from the node to a write-enabled connection","tags":["nodes"],"x-capability":"export_data"}},"/preview/nodes/{name}/data-exports/{id}":{"get":{"description":"Status of an export (export_data): \"running\" (with bytes_transferred, plus files_done/files_total on a platform-storage tree export), \"complete\" ({total_bytes, dest}), or \"failed\" with the provider's real error relayed verbatim - an access failure names the connection so a human can fix it. Status checks never wake a stopped node; an export interrupted by node stop or worker loss reports \"failed\" honestly and is safe to re-run (re-call export_data; the destination object is replaced, never doubled - and a tree export resumes, skipping objects already landed).","operationId":"get_get_export","parameters":[{"description":"Node name (from `list_nodes`).","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`).","type":"string"},"x-property":"node"},{"description":"Export id from export_data (e.g. \"exp-4kd93\").","in":"path","name":"id","required":true,"schema":{"description":"Export id from export_data (e.g. \"exp-4kd93\").","type":"string"},"x-property":"export_id"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"Export status: running/complete/failed (provider errors verbatim)","tags":["nodes"],"x-capability":"get_export"}},"/preview/nodes/{name}/doctor":{"post":{"description":"Preflight ONE of your nodes from the inside: run environment checks in its container and report what would break a build before you start one. This is the tenant-scoped counterpart to `doctor` (which reports fleet invariants for operators, not your node). Checks: torch's CUDA major vs the image's nvcc - the mismatch that makes building flash-attn / DeepSpeed / apex / xformers impossible on an image whose toolkit disagrees with the torch pip resolved, and which otherwise fails only after a long compile; the container's cgroup CPU budget vs the host numbers os.cpu_count()/free/psutil report, which is what makes an os.cpu_count()-sized pool over-subscribe; virtualenvs that no longer load under the current image (the usual cause is a snapshot restored onto a different one); and whether the GPU actually computes, via a one-line matmul. Answers {ok, findings:[{check, problem, fix}], passed, skipped:[{check, reason}], facts}. A check that does not apply here (no CUDA toolkit, no torch installed, no venvs) is SKIPPED with a reason, never reported as a problem. Nothing is installed, repaired, or changed - it only looks. The node must be running, and unlike run_command this NEVER wakes a stopped one (a preflight should not start billing to answer); on a running node it is an exec, so it counts as activity and re-arms the idle grace. Run it after you set up an environment and before a long build.","operationId":"post_node_doctor","parameters":[{"description":"Node name (from `list_nodes`). The node must already be running:\nthe checks run INSIDE its container, and this never wakes a stopped\nnode.","in":"path","name":"name","required":true,"schema":{"description":"Node name (from `list_nodes`). The node must already be running:\nthe checks run INSIDE its container, and this never wakes a stopped\nnode.","type":"string"},"x-property":"node"},{"$ref":"#/components/parameters/Workspace"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"503":{"$ref":"#/components/responses/Settling"}},"summary":"Preflight the node's environment from inside its container","tags":["nodes"],"x-capability":"node_doctor"}},"/preview/nodes/{name}/endpoints":{"get":{"description":"List live HTTPS-ingress endpoints: {endpoints: [{endpoint_id, url, port, auth, created_at, expires_at}]}. Pass `name` for a NODE's endpoints or `sandbox` for a SANDBOX's. For a node, only endpoints on its CURRENT container appear: a stop killed the older generations' endpoints (expose_port after the wake mints fresh URLs). For a sandbox, every live endpoint appears - a sandbox has no generations, it either exists or it does not.","operationId":"get_list_endpoints","parameters":[{"description":"Node name (from `list_nodes`). Pass this OR `sandbox`.","in":"path","name":"name","required":true,"schema":{"default":null,"description":"Node name (from `list_nodes`). Pass this OR `sandbox`.","type":["string","null"]},"x-property":"name"},{"$ref":"#/components/parameters/Workspace"}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"sandbox":{"default":null,"description":"A sandbox id instead of a node name, for the ports exposed on one\nof your sandboxes (docs/designs/sbx-inbound-ports.md).","type":["string","null"]}},"type":"object"}}},"description":"The capability's remaining parameters. Path and query parameters overlay these keys, so a value here that the URL also names is ignored.","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}},"description":"The capability's JSON result.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Refused"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"}},"summary":"The node's exposed endpoints","tags":["nodes"],"x-capability":"list_endpoints"},"post":{"description":"Expose a port on a RUNNING node at a public HTTPS URL, so anything that can curl can reach a server inside the node (TensorBoard, Jupyter, a vLLM endpoint serving a model to a judge). Returns {endpoint_id, url, port, auth, expires_at}. Default auth is the capability URL itself: anyone holding the URL reaches the port, so treat it like a secret. auth:\"bearer\" additionally requires `Authorization: Bearer ` at the edge; the token rides the response ONCE and is never shown again. The endpoint is bound to the node's current container: node stop kills it, and a wake never resurrects it (re-call expose_port for a fresh URL). Traffic through the endpoint does NOT keep the node awake and is not billed; the server process (a detached run_command) is what holds the node running. Re-calling for an already-exposed port is idempotent: same URL, refreshed expiry. Never wakes a stopped node: wake it first (any run_command), then expose. Raw byte pipe behind the URL: streaming, SSE, and WebSocket all pass through. `vanity: \"