{ "components": { "schemas": { "Compute": { "description": "A set of machines held under one intention, as the API serves it.\n\n``spec`` is what was asked for and ``status`` is what was observed, written by\ndifferent actors and kept in one resource so that reading both is one call.\n``revision`` is the concurrency token behind ``ETag`` and ``If-Match``;\n``generation`` counts definitions, not writes.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "generation": { "type": "integer" }, "id": { "type": "string" }, "lease": { "$ref": "#/components/schemas/Lease" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "revision": { "type": "integer" }, "spec": { "$ref": "#/components/schemas/ComputeSpec" }, "status": { "$ref": "#/components/schemas/ComputeStatus" } }, "required": [ "created_at", "generation", "id", "lease", "name", "revision", "spec", "status" ], "title": "Compute", "type": "object" }, "ComputeAbandoned": { "description": "Nothing renewed the lease and ``delete_on_exit`` was set, so it is going away.\n\nIts own fact rather than a compute state, because a lapsed lease is not a\nfailure \u2014 it is what a client exiting looks like from in here.", "properties": { "compute": { "type": "string" }, "type": { "const": "compute.abandoned", "type": "string" } }, "required": [ "compute", "type" ], "title": "ComputeAbandoned", "type": "object" }, "ComputeCreate": { "description": "What it takes to ask for a compute: a definition, and optionally a name to find it by.", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "spec": { "$ref": "#/components/schemas/ComputeSpec" } }, "required": [ "spec" ], "title": "ComputeCreate", "type": "object" }, "ComputeEvent": { "description": "A compute reached a state worth saying out loud.\n\nCarried by ``compute.ready``, ``compute.degraded`` and ``compute.deleted``.\nNot every state gets one: the stream reports the transitions a watcher acts\non, not every pass the reconciler makes.", "properties": { "compute": { "type": "string" }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "requested", "provisioning", "recovering", "ready", "degraded", "deleting", "deleted", "failed" ], "type": "string" }, "type": { "const": "compute.state", "type": "string" } }, "required": [ "compute", "state", "type" ], "title": "ComputeEvent", "type": "object" }, "ComputeSpec": { "description": "Everything a compute was asked to be. Intent, never observation.\n\nOnly a client writes it, and only through ``PATCH``. Of its fields exactly one\nis mutable in place \u2014 ``nodes``, which resizes \u2014 and changing any other is\ndrift: it is recorded, the applied definition is kept, and replacing the\nmachines takes a new generation.", "properties": { "allocation": { "default": "spot_if_available", "enum": [ "spot", "on_demand", "spot_if_available", "cheapest" ], "type": "string" }, "delete_on_exit": { "default": false, "type": "boolean" }, "desired": { "default": "running", "enum": [ "running", "deleted" ], "type": "string" }, "image": { "$ref": "#/components/schemas/Image" }, "nodes": { "$ref": "#/components/schemas/NodeBounds" }, "options": { "$ref": "#/components/schemas/Options" }, "plugins": { "default": [], "items": { "$ref": "#/components/schemas/PluginRef" }, "type": "array" }, "retry": { "$ref": "#/components/schemas/RetryPolicy" }, "selection": { "default": "cheapest", "enum": [ "cheapest", "first" ], "type": "string" }, "specs": { "items": { "$ref": "#/components/schemas/Spec" }, "type": "array" }, "ttl": { "default": 600, "type": "integer" }, "volumes": { "default": [], "items": { "$ref": "#/components/schemas/Volume" }, "type": "array" }, "worker": { "$ref": "#/components/schemas/Worker" } }, "required": [ "nodes", "specs" ], "title": "ComputeSpec", "type": "object" }, "ComputeSpecPatch": { "description": "The one field of a spec that can change without replacing machines.", "properties": { "nodes": { "$ref": "#/components/schemas/NodeBounds" } }, "required": [ "nodes" ], "title": "ComputeSpecPatch", "type": "object" }, "ComputeStatus": { "description": "What the reconciler has observed. Never written by a client.\n\n``observed_generation`` against the compute's ``generation`` is the progress:\nthe gap between them *is* the pending work, which is why there is no operation\nresource to poll.", "properties": { "drift": { "default": [], "items": { "type": "string" }, "type": "array" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] }, "nodes_ready": { "type": "integer" }, "nodes_total": { "type": "integer" }, "observed_generation": { "type": "integer" }, "state": { "enum": [ "requested", "provisioning", "recovering", "ready", "degraded", "deleting", "deleted", "failed" ], "type": "string" } }, "required": [ "nodes_ready", "nodes_total", "observed_generation", "state" ], "title": "ComputeStatus", "type": "object" }, "ConsoleEvent": { "description": "A line a node printed, and the task it belongs to when it belongs to one.\n\nRecorded, because output that only existed live would be output a client that\nreconnected could never see.", "properties": { "compute": { "type": "string" }, "content": { "type": "string" }, "node": { "type": "string" }, "task": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "const": "node.console", "type": "string" } }, "required": [ "compute", "content", "node", "type" ], "title": "ConsoleEvent", "type": "object" }, "CostEvent": { "description": "What the compute has accrued so far, and over how many live machines.\n\nPublished rather than recorded: a gauge sampled every few seconds has no\nreplay value, and the event log has no GC to save it from one.", "properties": { "at": { "format": "date-time", "type": "string" }, "compute": { "type": "string" }, "cost": { "type": "number" }, "nodes": { "type": "integer" }, "type": { "const": "compute.cost", "type": "string" } }, "required": [ "at", "compute", "cost", "nodes", "type" ], "title": "CostEvent", "type": "object" }, "Error": { "description": "Every failure, in one shape, whatever produced it.\n\n``code`` is the closed set a client matches on, so nobody parses prose.\n``retryable`` is a property of the failure rather than a guess left to the\ncaller: a revision conflict is worth re-reading and re-sending, and a spec no\nprovider can satisfy is not.", "properties": { "code": { "enum": [ "not_found", "revision_conflict", "idempotency_conflict", "lease_held", "compute_not_accepting", "unsupported_provider", "unsupported_plugin", "secret_in_definition", "hash_mismatch", "task_failed", "task_indeterminate", "duplication_not_acknowledged", "capability_mismatch", "release_pending" ], "type": "string" }, "details": { "oneOf": [ { "additionalProperties": {}, "type": "object" }, { "type": "null" } ] }, "message": { "type": "string" }, "request_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ], "title": "Error", "type": "object" }, "Execution": { "description": "One physical attempt at a task.\n\n``ordinal`` counts the attempts and ``rank`` says which node took it. A retry\nis another execution pointing ``retry_of`` at the last one \u2014 never another\ntask, because the task id is the handle the caller is holding.", "properties": { "error": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "node_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "ordinal": { "type": "integer" }, "rank": { "type": "integer" }, "result_sha256": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_of": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "started_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "created", "assigned", "dispatching", "accepted", "started", "cancel_requested", "succeeded", "failed", "cancelled", "timed_out", "indeterminate" ], "type": "string" } }, "required": [ "id", "ordinal", "rank", "state" ], "title": "Execution", "type": "object" }, "ExecutionCreate": { "description": "A retry, and the admission that it may be a second run.\n\n``acknowledge_duplication`` is required to retry an indeterminate outcome: the\nsystem does not know whether the previous attempt had side effects, and the\ncaller is the only one in a position to say that running twice is acceptable.", "properties": { "acknowledge_duplication": { "default": false, "type": "boolean" }, "ranks": { "oneOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ] } }, "required": [], "title": "ExecutionCreate", "type": "object" }, "Function": { "description": "A registered piece of code, named by the hash of its serialized bytes.\n\nThe metadata only. The code is a blob, fetched as one \u2014 which is what lets a\ntask name its function without carrying it.", "properties": { "codec": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer" } }, "required": [ "codec", "created_at", "sha256", "size_bytes" ], "title": "Function", "type": "object" }, "Generation": { "description": "One frozen definition of a compute, and whether the machines match it yet.\n\nHistory is kept rather than overwritten, because a rollback is a generation\ntoo \u2014 it is a new number carrying an old spec, not an erasure of what happened\nin between.", "properties": { "applied": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "hash": { "type": "string" }, "number": { "type": "integer" }, "spec": { "$ref": "#/components/schemas/ComputeSpec" } }, "required": [ "applied", "created_at", "hash", "number", "spec" ], "title": "Generation", "type": "object" }, "GenerationCreate": { "description": "Replace the machines: with the pending drift, or with an older definition.\n\nWithout ``source`` this applies whatever drift the status is carrying. With\none, it rolls back to that generation. ``force`` marks unresolved tasks\nindeterminate rather than refusing while executions are still live.", "properties": { "force": { "default": false, "type": "boolean" }, "source": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [], "title": "GenerationCreate", "type": "object" }, "Image": { "description": "The environment a node builds before it runs anything.\n\nThe base, the interpreter, the packages and where they resolve from. What the\nuser shipped from their own machine is not here \u2014 ``includes`` is packed into\na blob client-side and only its hash travels, because a spec is written to the\ncompute row and served back by the API.", "properties": { "apt": { "default": [], "items": { "type": "string" }, "type": "array" }, "base": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "bootstrap_timeout": { "default": 900, "type": "integer" }, "env": { "additionalProperties": { "type": "string" }, "type": "object" }, "excludes": { "default": [], "items": { "type": "string" }, "type": "array" }, "includes": { "default": [], "items": { "type": "string" }, "type": "array" }, "includes_sha256": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "metrics": { "oneOf": [ { "items": { "$ref": "#/components/schemas/MetricSpec" }, "type": "array" }, { "type": "null" } ] }, "pip": { "default": [], "items": { "type": "string" }, "type": "array" }, "pip_indexes": { "default": [], "items": { "$ref": "#/components/schemas/PipIndex" }, "type": "array" }, "python": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "shell_vars": { "additionalProperties": { "type": "string" }, "type": "object" }, "skyward": { "default": "auto", "enum": [ "auto", "local", "github", "pypi" ], "type": "string" }, "warm": { "default": false, "type": "boolean" } }, "required": [], "title": "Image", "type": "object" }, "Lease": { "description": "Who currently owns the compute, and until when.\n\nA liveness signal the owning process renews, not a lock on the resource. Zero\nowners is legitimate and temporary \u2014 a daemon restarting, a script killed \u2014\nand only the holder opens SSH connections to the machines. Losing it destroys\nnothing by itself.", "properties": { "expires_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "owner": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [], "title": "Lease", "type": "object" }, "LeaseClaim": { "description": "A bid for ownership: who is claiming, and for how long before it lapses.", "properties": { "owner": { "type": "string" }, "ttl_seconds": { "type": "integer" } }, "required": [ "owner", "ttl_seconds" ], "title": "LeaseClaim", "type": "object" }, "Liveness": { "description": "Whether the process answers. Says nothing about the store or the providers.", "properties": { "live": { "type": "boolean" } }, "required": [ "live" ], "title": "Liveness", "type": "object" }, "MetricEvent": { "description": "One gauge reading off one node. Published rather than recorded, like ``compute.cost``.", "properties": { "compute": { "type": "string" }, "name": { "type": "string" }, "node": { "type": "string" }, "type": { "const": "node.metrics", "type": "string" }, "value": { "type": "number" } }, "required": [ "compute", "name", "node", "type", "value" ], "title": "MetricEvent", "type": "object" }, "MetricSpec": { "description": "One reading a node takes about itself: a shell command, sampled on a period.\n\nThe command must print a bare number; anything else is dropped rather than\nreported. ``interval`` is in seconds.", "properties": { "command": { "type": "string" }, "interval": { "type": "number" }, "name": { "type": "string" } }, "required": [ "command", "interval", "name" ], "title": "MetricSpec", "type": "object" }, "Node": { "description": "One machine, ranked, as the control plane knows it.\n\nThe row exists before the provider is asked for a machine, which is what makes\nprovisioning idempotent \u2014 ``machine`` is null until there is one to name. A\nnode that died keeps its row and its ``provider_binding`` until the provider\nconfirms the instance is gone, so nothing goes missing unnoticed.", "properties": { "accelerator": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_unit": { "oneOf": [ { "enum": [ "second", "minute", "hour" ], "type": "string" }, { "type": "null" } ] }, "compute_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "desired": { "enum": [ "present", "deleted" ], "type": "string" }, "generation": { "type": "integer" }, "id": { "type": "string" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] }, "launched_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "machine": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "market": { "oneOf": [ { "enum": [ "spot", "on_demand" ], "type": "string" }, { "type": "null" } ] }, "price_per_hour": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "provider_binding": { "additionalProperties": {}, "type": "object" }, "rank": { "type": "integer" }, "revision": { "type": "integer" }, "state": { "enum": [ "requested", "provisioning", "connecting", "bootstrapping", "ready", "draining", "lost", "deleting", "deleted", "failed" ], "type": "string" }, "terminated_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "compute_id", "created_at", "desired", "generation", "id", "provider_binding", "rank", "revision", "state" ], "title": "Node", "type": "object" }, "NodeBounds": { "description": "How many machines, and how much of that is negotiable.\n\n``desired`` is the target. ``min`` is the count at which work may start, which\nis what lets a job of eight begin on four. ``max`` is the ceiling autoscaling\nmay reach. Both unset means the target is also the floor and the ceiling.", "properties": { "desired": { "type": "integer" }, "max": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "min": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "desired" ], "title": "NodeBounds", "type": "object" }, "NodeEvent": { "description": "One machine's lifecycle moved, carried by every ``node.{state}``.\n\n``state`` repeats the event name because a payload that has been written\ndown, exported, or replayed out of the stream has to say what it is without\nthe frame that carried it.", "properties": { "compute": { "type": "string" }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "node": { "type": "string" }, "state": { "enum": [ "requested", "provisioning", "connecting", "bootstrapping", "ready", "draining", "lost", "deleting", "deleted", "failed" ], "type": "string" }, "type": { "const": "node.state", "type": "string" } }, "required": [ "compute", "node", "state", "type" ], "title": "NodeEvent", "type": "object" }, "Offer": { "description": "One buyable machine shape from one account, normalized.\n\nThe accelerator name and its VRAM are parsed into the shared vocabulary here\nrather than in each adapter, which is what stops the same GPU from being two\ndifferent accelerators depending on who is selling it. ``price`` is the\ncheapest the offer can be had for, and it is what ordering and budget filters\ncompare on.", "properties": { "accelerator": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "accelerator_count": { "type": "integer" }, "architecture": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "available": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "billing_unit": { "default": "hour", "enum": [ "second", "minute", "hour" ], "type": "string" }, "cpus": { "type": "integer" }, "disk_gb": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "format": "date-time", "type": "string" }, "fetched_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "instance_type": { "type": "string" }, "kind": { "type": "string" }, "memory_gb": { "type": "number" }, "on_demand_price": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "price": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "region": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "specific": { "additionalProperties": {}, "type": "object" }, "spot_price": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vram": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "accelerator_count", "cpus", "expires_at", "fetched_at", "id", "instance_type", "kind", "memory_gb", "provider_id", "provider_name" ], "title": "Offer", "type": "object" }, "Options": { "default": { "autoscale_cooldown": 0.0, "autoscale_idle_timeout": 30.0, "cluster": null, "default_compute_timeout": 0.0, "health_command": null, "health_failures": 3, "health_function": null, "health_initial_delay": 0.0, "health_interval": 30.0, "health_timeout": 15.0, "ssh_connect_timeout": 300.0, "ssh_reconnect_attempts": 30, "ssh_retry_delay": 2.0, "worker_timeout": 180.0 }, "description": "Operational knobs the daemon reads off the spec.\n\nEach defaults to the value the runtime hard-coded before the knob existed, so a\nspec built without options behaves exactly as one built with ``Options()``. The\nclient-side timeouts are not here: they govern how long the owning process waits\nfor its own pool, never leave it, and so ride the SDK's ``Options`` rather than\nthe wire.", "properties": { "autoscale_cooldown": { "default": 0.0, "type": "number" }, "autoscale_idle_timeout": { "default": 30.0, "type": "number" }, "cluster": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "default_compute_timeout": { "default": 0.0, "type": "number" }, "health_command": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "health_failures": { "default": 3, "type": "integer" }, "health_function": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "health_initial_delay": { "default": 0.0, "type": "number" }, "health_interval": { "default": 30.0, "type": "number" }, "health_timeout": { "default": 15.0, "type": "number" }, "ssh_connect_timeout": { "default": 300.0, "type": "number" }, "ssh_reconnect_attempts": { "default": 30, "type": "integer" }, "ssh_retry_delay": { "default": 2.0, "type": "number" }, "worker_timeout": { "default": 180.0, "type": "number" } }, "required": [], "title": "Options", "type": "object" }, "Page_skyward.shared.schemas.Compute_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Compute" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Compute]", "type": "object" }, "Page_skyward.shared.schemas.Execution_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Execution" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Execution]", "type": "object" }, "Page_skyward.shared.schemas.Function_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Function" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Function]", "type": "object" }, "Page_skyward.shared.schemas.Generation_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Generation" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Generation]", "type": "object" }, "Page_skyward.shared.schemas.Node_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Node" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Node]", "type": "object" }, "Page_skyward.shared.schemas.Offer_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Offer" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Offer]", "type": "object" }, "Page_skyward.shared.schemas.Provider_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Provider" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Provider]", "type": "object" }, "Page_skyward.shared.schemas.Task_": { "description": "A slice of a listing, and the cursor that continues it.\n\n``next_cursor`` is null on the last page. Cursors are opaque and are not\noffsets \u2014 a row inserted mid-walk does not shift what a held cursor returns.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Task" }, "type": "array" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items" ], "title": "Page[Task]", "type": "object" }, "PhaseEvent": { "description": "A bootstrap phase turning over, so a late subscriber replays the checklist.\n\n``phase`` names the step; ``event`` says whether it opened, closed, or broke.", "properties": { "at": { "format": "date-time", "type": "string" }, "compute": { "type": "string" }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "event": { "enum": [ "started", "completed", "failed" ], "type": "string" }, "node": { "type": "string" }, "phase": { "type": "string" }, "type": { "const": "node.phase", "type": "string" } }, "required": [ "at", "compute", "event", "node", "phase", "type" ], "title": "PhaseEvent", "type": "object" }, "PipIndex": { "description": "A package index the resolver should reach for, and what it may serve.\n\n``packages`` is the scope: only those names resolve from ``url`` (uv's\n``explicit = true``), so a private index cannot silently answer for a public\npackage. An empty scope makes it an ordinary extra index.", "properties": { "packages": { "default": [], "items": { "type": "string" }, "type": "array" }, "url": { "type": "string" } }, "required": [ "url" ], "title": "PipIndex", "type": "object" }, "PluginRef": { "description": "A plugin as it travels: a name and its parameters, never an object.\n\nA plugin is rebuilt on the node from exactly this, which is why it cannot hold\na closure or a live handle. Its behaviour is its class's methods; its identity\nis ``kind``.", "properties": { "kind": { "type": "string" }, "params": { "additionalProperties": {}, "type": "object" } }, "required": [ "kind" ], "title": "PluginRef", "type": "object" }, "Provider": { "description": "A registered account, as the API serves it \u2014 which is to say, without its secrets.\n\n``offers_fetched_at`` and ``offers_count`` describe the cached catalog behind\nit, and ``last_error`` is why the last refresh failed. A failed refresh leaves\nthe stale offers in place: stale offers beat no offers.", "properties": { "config": { "additionalProperties": {}, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ] }, "name": { "type": "string" }, "offers_count": { "default": 0, "type": "integer" }, "offers_fetched_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "offers_ttl_seconds": { "type": "integer" } }, "required": [ "config", "created_at", "id", "kind", "name", "offers_ttl_seconds" ], "title": "Provider", "type": "object" }, "ProviderCreate": { "description": "An account to register: what to call it, which cloud it is, and what opens it.\n\n``credentials`` are validated against the kind's declared fields before the\nrow is written, and no read path returns them afterwards.", "properties": { "config": { "additionalProperties": {}, "type": "object" }, "credentials": { "additionalProperties": { "type": "string" }, "type": "object" }, "kind": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "name" ], "title": "ProviderCreate", "type": "object" }, "ProviderKind": { "description": "A kind of cloud this build can talk to, and what registering one needs.\n\nCapability negotiation, before anything is created: a kind absent from this\nlist cannot be registered, usually because its SDK is not installed.", "properties": { "credential_fields": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "offers_ttl_seconds": { "type": "integer" } }, "required": [ "credential_fields", "kind", "offers_ttl_seconds" ], "title": "ProviderKind", "type": "object" }, "ProviderRef": { "description": "Which account a spec wants to buy from, and how that account is configured.", "properties": { "config": { "additionalProperties": {}, "type": "object" }, "kind": { "type": "string" } }, "required": [ "kind" ], "title": "ProviderRef", "type": "object" }, "Readiness": { "description": "Whether the daemon can serve: schema in place, recovery done.", "properties": { "ready": { "type": "boolean" } }, "required": [ "ready" ], "title": "Readiness", "type": "object" }, "Result": { "description": "What one command said on one machine: its exit code and both its streams.", "properties": { "exit_code": { "type": "integer" }, "stderr": { "type": "string" }, "stdout": { "type": "string" } }, "required": [ "exit_code", "stderr", "stdout" ], "title": "Result", "type": "object" }, "RetryPolicy": { "default": { "ambiguous_retries": 0, "safe_retries": 3 }, "description": "How many times to try again, split by whether trying again is safe.\n\nA task that never started can be re-run freely. A task whose node went silent\nafter it may have run is a different question, and it defaults to zero because\nthe system does not know whether it had side effects and will not pretend to.", "properties": { "ambiguous_retries": { "default": 0, "type": "integer" }, "safe_retries": { "default": 3, "type": "integer" } }, "required": [], "title": "RetryPolicy", "type": "object" }, "Spec": { "description": "One shape of machine that would do, from one account.\n\nA compute carries several of these as a preference list and buys exactly one:\neverything here is what the market filters offers on, and everything that must\nbe true of the whole fleet \u2014 volumes, plugins, node counts \u2014 is on the compute\ninstead.", "properties": { "accelerator": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "accelerator_count": { "default": 1, "type": "integer" }, "architecture": { "oneOf": [ { "enum": [ "x86_64", "arm64" ], "type": "string" }, { "type": "null" } ] }, "cpus": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gb": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_hourly_cost": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "memory_gb": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/ProviderRef" }, "region": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "provider" ], "title": "Spec", "type": "object" }, "Task": { "description": "One call \u2014 function plus arguments \u2014 and its one terminal outcome.\n\nAppend-only. ``state`` is derived from the executions rather than written\nbeside them, and is stored only so that listing by state is a query instead of\na scan. ``correlation_id`` is how the tasks of one ``&``, ``gather`` or ``map``\nare found together: a field on each of them, not a resource of their own.", "properties": { "args_sha256": { "type": "string" }, "compute_id": { "type": "string" }, "correlation_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "deadline_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "dispatch": { "enum": [ "one", "all", "stream" ], "type": "string" }, "executions": { "items": { "$ref": "#/components/schemas/Execution" }, "type": "array" }, "finished_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "function": { "type": "string" }, "generation": { "type": "integer" }, "id": { "type": "string" }, "result_sha256": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "retry": { "$ref": "#/components/schemas/RetryPolicy" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "timed_out", "indeterminate" ], "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" } }, "required": [ "args_sha256", "compute_id", "dispatch", "executions", "function", "generation", "id", "retry", "state", "submitted_at" ], "title": "Task", "type": "object" }, "TaskCreate": { "description": "One call to place: the code, its arguments, and how widely to run it.\n\nArguments travel inline below a size threshold and as a blob above it, which\nis why there are two fields for them and exactly one is set.", "properties": { "args_inline": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "args_sha256": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "compute": { "type": "string" }, "correlation_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "dispatch": { "enum": [ "one", "all", "stream" ], "type": "string" }, "function": { "type": "string" }, "rank": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "retry": { "oneOf": [ { "$ref": "#/components/schemas/RetryPolicy" } ] }, "timeout_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "compute", "dispatch", "function" ], "title": "TaskCreate", "type": "object" }, "TaskEvent": { "description": "A task began, or reached the one terminal outcome it is allowed.", "properties": { "compute": { "type": "string" }, "state": { "enum": [ "started", "succeeded", "failed", "indeterminate" ], "type": "string" }, "task": { "type": "string" }, "type": { "const": "task.state", "type": "string" } }, "required": [ "compute", "state", "task", "type" ], "title": "TaskEvent", "type": "object" }, "Volume": { "description": "A bucket the nodes read and write as a directory.\n\n``bucket`` names an object-storage bucket, except on providers that attach a\nvolume of their own rather than mounting one \u2014 RunPod reads it as the id or\nname of a network volume.\n\nWhere the credentials come from is what ``storage_sha256`` decides, and it is\nthe only reason the field exists. ``None`` means the daemon resolves them from\nthe provider record it already holds, and nothing about the bucket's access\never reaches this struct. A digest means the client brought its own, put them\nin the blob store, and left only the hash here \u2014 because a spec is written to\nthe compute row and served back by the compute API, and a secret written there\nis a secret published.", "properties": { "bucket": { "type": "string" }, "mount": { "type": "string" }, "prefix": { "default": "", "type": "string" }, "read_only": { "default": true, "type": "boolean" }, "storage_sha256": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bucket", "mount" ], "title": "Volume", "type": "object" }, "Worker": { "default": { "buffer": 0, "concurrency": null, "executor": "thread", "reuse": true }, "description": "How much work a node takes at once, and what runs it.\n\n``concurrency`` unset lets the node decide from what it has. The executor is\nthe backend the tasks run on: threads by default, processes or loky when the\nwork holds the GIL.", "properties": { "buffer": { "default": 0, "type": "integer" }, "concurrency": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "executor": { "default": "thread", "enum": [ "thread", "process", "loky" ], "type": "string" }, "reuse": { "default": true, "type": "boolean" } }, "required": [], "title": "Worker", "type": "object" } } }, "info": { "description": "Two families of resource.\n\n**Declarative** (`compute`, `node`) carry `spec` (intent) and `status` (observation). `PATCH` only touches `spec`; `status` is written by the reconciler. There is no `operation` resource \u2014 `generation` vs `status.observed_generation` is the progress.\n\n**Imperative** (`task`) are append-only facts with one terminal outcome. `executions` are the physical attempts; retrying creates an execution, never a task, so a `Future` keeps a stable handle.", "title": "Skyward Control Plane", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/v1/blobs/{sha256}": { "get": { "deprecated": false, "description": "Reading does not consume it. A result read twice is the same bytes twice, which is what lets an SDK that restarted collect a result the process before it had already taken.", "operationId": "V1BlobsSha256Download", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.skyward.blob": { "schema": { "type": "string" } } }, "description": "The stored bytes" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Download a blob", "tags": [ "blobs" ] }, "head": { "deprecated": false, "description": "Whether this content is already here, so a client can skip an upload it does not need to make.", "operationId": "V1BlobsSha256Exists", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Check existence", "tags": [ "blobs" ] }, "put": { "deprecated": false, "description": "Small args go inline in `POST /tasks`. Above the threshold the SDK uploads here first and the task references the hash. Large results take the same path on the way back.\n\nThe body is the bytes themselves, and the name is what they hash to \u2014 content that does not hash to its name is refused with `hash_mismatch` rather than stored under a name that lies. Uploading content already here answers `200` and writes nothing.", "operationId": "V1BlobsSha256Upload", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/vnd.skyward.blob": { "schema": { "description": "The bytes themselves \u2014 what they hash to is the name they are stored under.", "format": "binary", "type": "string" } } }, "description": "Arguments, code, or a result \u2014 whatever the hash names.", "required": true }, "responses": { "200": { "description": "Already stored \u2014 the upload was a no-op" }, "201": { "content": { "application/json": { "schema": { "type": "null" } } }, "description": "Document created, URL follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Content does not hash to the name it was given \u2014 `hash_mismatch`" } }, "summary": "Upload a content-addressed blob", "tags": [ "blobs" ] } }, "/v1/computes": { "get": { "deprecated": false, "description": "Every compute this daemon knows about, including the deleted ones \u2014 a compute's row outlives its machines. `owned=false` lists the orphans: computes no live process is holding a lease on, which is what a compute looks like between the script that made it exiting and the next one attaching.", "operationId": "V1ComputesList", "parameters": [ { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "cursor", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "type": "integer" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "state", "required": false, "schema": { "oneOf": [ { "enum": [ "requested", "provisioning", "recovering", "ready", "degraded", "deleting", "deleted", "failed" ], "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "`false` lists orphans \u2014 computes with no live owner.", "in": "query", "name": "owned", "required": false, "schema": { "description": "`false` lists orphans \u2014 computes with no live owner.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Compute_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "List computes", "tags": [ "computes" ] }, "post": { "deprecated": false, "description": "Idempotent by `Idempotency-Key`: the same key with the same payload returns the original resource with `200`; with a different payload, `409 idempotency_conflict`.\n\nDoes not wait for readiness \u2014 returns `status.state: requested` and the client observes the resource or the event stream. There is no `operation` resource: `generation` vs `status.observed_generation` is the progress.", "operationId": "V1ComputesCreate", "parameters": [ { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compute" } } }, "description": "The compute this key already created" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compute" } } }, "description": "Document created, URL follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Create a compute", "tags": [ "computes" ] } }, "/v1/computes/{compute_id}": { "delete": { "deprecated": false, "description": "Writes `spec.desired: deleted`. Not synchronous, and not a detach: reconciliation continues until the provider **confirms the resources are gone**, and only then does `status.state` become `deleted`.\n\nNo process shutdown ever issues this command.", "operationId": "V1ComputesComputeIdDestroy", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compute" } } }, "description": "Request accepted, processing continues off-line", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`If-Match` did not name the stored revision \u2014 `revision_conflict`. Retryable: re-read, re-apply, re-send" } }, "summary": "Mark a compute for destruction", "tags": [ "computes" ] }, "get": { "deprecated": false, "description": "Accepts an id or a name. The response always carries both.", "operationId": "V1ComputesComputeIdRead", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compute" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a compute", "tags": [ "computes" ] }, "patch": { "deprecated": false, "description": "Only `spec.nodes` is mutable in place: it bumps `generation` and the reconciler resizes with drain.\n\nChanging immutable fields (provider, image, worker, plugins, volumes, ports) is **drift**: it is recorded in `status.drift`, the applied definition is kept, and no infrastructure is replaced. Replacing requires `POST /computes/{id}/generations`.", "operationId": "V1ComputesComputeIdUpdate", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeSpecPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compute" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`If-Match` did not name the stored revision \u2014 `revision_conflict`. Retryable: re-read, re-apply, re-send" } }, "summary": "Change a compute's spec", "tags": [ "computes" ] } }, "/v1/computes/{compute_id}/exec": { "post": { "deprecated": false, "description": "`command` in a shell on each targeted node, and what each one said. The machine's shell, not the worker's \u2014 this reaches a node whose worker is busy, and answers questions about the machine rather than about the code running on it.\n\nA task is the other thing, and `POST /tasks` is where it goes.", "operationId": "V1ComputesComputeIdExecRun", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The command line, run by the node's shell.", "in": "query", "name": "command", "required": true, "schema": { "description": "The command line, run by the node's shell.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Which nodes to reach: `all`, or a rank.", "in": "query", "name": "node", "required": false, "schema": { "default": "all", "description": "Which nodes to reach: `all`, or a rank.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/Result" }, "type": "object" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Run a shell command on the compute", "tags": [ "files" ] } }, "/v1/computes/{compute_id}/files": { "delete": { "deprecated": false, "description": "`rm -rf` of `path`, per node. Defaults to every node, because a file left on one machine of four is the state a later broadcast reads and disagrees about.", "operationId": "V1ComputesComputeIdFilesRm", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The path to remove, on the node.", "in": "query", "name": "path", "required": true, "schema": { "description": "The path to remove, on the node.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Which nodes to reach: `all`, or a rank.", "in": "query", "name": "node", "required": false, "schema": { "default": "all", "description": "Which nodes to reach: `all`, or a rank.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/Result" }, "type": "object" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Remove a path on the compute", "tags": [ "files" ] }, "get": { "deprecated": false, "description": "`ls -la` of `path`, per node. Defaults to rank 0 \u2014 one listing is usually the question.", "operationId": "V1ComputesComputeIdFilesLs", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The path to list, on the node.", "in": "query", "name": "path", "required": true, "schema": { "description": "The path to list, on the node.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Which nodes to reach: `all`, or a rank.", "in": "query", "name": "node", "required": false, "schema": { "default": "0", "description": "Which nodes to reach: `all`, or a rank.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/Result" }, "type": "object" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "List a path on the compute", "tags": [ "files" ] }, "put": { "deprecated": false, "description": "The request body, written to `path`. Defaults to every node: code and data a task will read have to be wherever the task lands, and which node that is belongs to the dispatcher.\n\nThe answer is per node \u2014 a machine that refused the write is a line of it, not the end of it.", "operationId": "V1ComputesComputeIdFilesUpload", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Where to write it, on the node.", "in": "query", "name": "path", "required": true, "schema": { "description": "Where to write it, on the node.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Which nodes to reach: `all`, or a rank.", "in": "query", "name": "node", "required": false, "schema": { "default": "all", "description": "Which nodes to reach: `all`, or a rank.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Write a file onto the compute", "tags": [ "files" ] } }, "/v1/computes/{compute_id}/files/content": { "get": { "deprecated": false, "description": "`path` from one node, as a raw byte stream. `node=all` is refused rather than picked between: four machines hold four files, and concatenating them would answer a question nobody asked.", "operationId": "V1ComputesComputeIdFilesContentDownload", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The path to read, on the node.", "in": "query", "name": "path", "required": true, "schema": { "description": "The path to read, on the node.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Which node to read from: a rank.", "in": "query", "name": "node", "required": false, "schema": { "default": "0", "description": "Which node to read from: a rank.", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "The file's bytes, as the node reads them off disk" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Read a file off the compute", "tags": [ "files" ] } }, "/v1/computes/{compute_id}/forward/down": { "get": { "deprecated": false, "description": "The node's bytes back to the caller, as a raw byte stream \u2014 no framing, because a byte proxy has no frames. Waits for the matching `up` to open the channel, then follows it until the node closes its side.\n\nNot resumable. A dropped stream is a dead connection; open another.", "operationId": "V1ComputesComputeIdForwardDownDown", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The connection id shared with `up`.", "in": "query", "name": "cid", "required": true, "schema": { "description": "The connection id shared with `up`.", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Whatever the node sends back, unframed, until it closes its side" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "The down half of a forwarded connection", "tags": [ "forward" ] } }, "/v1/computes/{compute_id}/forward/up": { "post": { "deprecated": false, "description": "The caller's bytes into a node, as a streaming request body. **This request is the dispatch**: it opens the channel to a ready node \u2014 round-robin, unless `route` says otherwise \u2014 and pumps the body into it until the body ends.\n\nThe body is the socket. It has no length and closes only when the connection does, which is why it is streamed rather than read: waiting for the end would be waiting for the caller to hang up.\n\nPaired with `GET .../down` by the `cid` the caller mints \u2014 the two are one connection, and HTTP/1.1 will not carry both directions on a single request.", "operationId": "V1ComputesComputeIdForwardUpUp", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The connection id, minted by the caller, shared with `down`.", "in": "query", "name": "cid", "required": true, "schema": { "description": "The connection id, minted by the caller, shared with `down`.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The port the service listens on inside the node.", "in": "query", "name": "port", "required": true, "schema": { "description": "The port the service listens on inside the node.", "type": "integer" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "route", "required": false, "schema": { "const": "round_robin", "default": "round_robin", "type": "string" } } ], "responses": { "200": { "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "The up half of a forwarded connection", "tags": [ "forward" ] } }, "/v1/computes/{compute_id}/generations": { "get": { "deprecated": false, "description": "Every definition this compute has had, newest last. A rollback is a generation too, so this grows.", "operationId": "V1ComputesComputeIdGenerationsListGenerations", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Generation_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "List definition history", "tags": [ "computes" ] }, "post": { "deprecated": false, "description": "Replacing infrastructure *is* creating a new generation: quiesce, drain, destroy the old one, provision the new one \u2014 same `compute_id`.\n\nWithout `source`, applies the drift pending in `status.drift`. With `source`, rolls back to that generation.\n\n`force: true` marks unresolved tasks as `indeterminate` before replacing; `force: false` refuses while executions are still active.", "operationId": "V1ComputesComputeIdGenerationsCreateGeneration", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } }, "description": "Request accepted, processing continues off-line", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`If-Match` did not name the stored revision \u2014 `revision_conflict`. Retryable: re-read, re-apply, re-send" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Create a generation (apply drift, or roll back)", "tags": [ "computes" ] } }, "/v1/computes/{compute_id}/generations/{number}": { "get": { "deprecated": false, "description": "One definition as it was frozen, and whether the machines were ever built to match it.", "operationId": "V1ComputesComputeIdGenerationsNumberGetGeneration", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "path", "name": "number", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generation" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a generation", "tags": [ "computes" ] } }, "/v1/computes/{compute_id}/lease": { "delete": { "deprecated": false, "description": "Orderly detach: drops the claim without touching `spec.desired`. Destroys nothing.", "operationId": "V1ComputesComputeIdLeaseReleaseLease", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Request fulfilled, nothing follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Release ownership", "tags": [ "computes" ] }, "put": { "deprecated": false, "description": "A compute has at most one live owner per generation; zero is legitimate and temporary (daemon restarting, script killed).\n\nClaiming requires the current lease to be expired or absent \u2014 it is a CAS. Renewing requires being the current owner. Losing renewals destroys nothing by itself: if `spec.delete_on_exit` is `true`, reconciliation tears the compute down; if `false`, it simply sits ownerless until something adopts it.", "operationId": "V1ComputesComputeIdLeaseClaimLease", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseClaim" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lease" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" } }, "summary": "Claim or renew ownership", "tags": [ "computes" ] } }, "/v1/computes/{compute_id}/nodes": { "get": { "deprecated": false, "description": "Includes tombstones by default. A node that died stays listed, with its `provider_binding` intact, until the provider confirms termination \u2014 that is what stops an instance from going missing with nobody knowing.", "operationId": "V1ComputesComputeIdNodesList", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "include_terminal", "required": false, "schema": { "default": true, "type": "boolean" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "generation", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Node_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "List a compute's nodes", "tags": [ "nodes" ] } }, "/v1/computes/{compute_id}/nodes/{node_id}": { "delete": { "deprecated": false, "description": "Nodes are not directly creatable \u2014 they come from reconciling `spec.nodes`. But a node can be condemned: `desired: deleted` blocks new assignments, waits for the executions it is known to hold, then destroys the instance.\n\nIf the compute still wants that capacity, the reconciler creates **another** node for the same `rank`, with a new `id`. The old node's tombstone remains.", "operationId": "V1ComputesComputeIdNodesNodeIdDrain", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "path", "name": "node_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node" } } }, "description": "Request accepted, processing continues off-line", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" } }, "summary": "Drain and replace a node", "tags": [ "nodes" ] }, "get": { "deprecated": false, "description": "One machine as the control plane knows it, including the `provider_binding` it was launched under.", "operationId": "V1ComputesComputeIdNodesNodeIdRead", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "path", "name": "node_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Node" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a node", "tags": [ "nodes" ] } }, "/v1/computes/{compute_id}/shell/down": { "get": { "deprecated": false, "description": "What the terminal paints, as a raw byte stream \u2014 no framing, because a terminal has none, and the error stream is folded in because a terminal has one output. Waits for the matching `up` to open the session, then follows it until the shell exits.\n\nNot resumable. A dropped stream is a dead session; open another.", "operationId": "V1ComputesComputeIdShellDownDown", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The session id shared with `up`.", "in": "query", "name": "cid", "required": true, "schema": { "description": "The session id shared with `up`.", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Whatever the terminal paints, unframed, until the shell exits" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "The down half of an interactive session", "tags": [ "shell" ] } }, "/v1/computes/{compute_id}/shell/up": { "post": { "deprecated": false, "description": "The caller's keystrokes into a node's terminal, as a streaming request body. **This request is the dispatch**: it opens the pseudo-terminal \u2014 on `node` if given, else on the first ready node \u2014 and pumps the body into it until the body ends.\n\nThe body is the keyboard. It has no length and closes only when the session does.\n\nPaired with `GET .../down` by the `cid` the caller mints \u2014 the two are one session, and HTTP/1.1 will not carry both directions on a single request.", "operationId": "V1ComputesComputeIdShellUpUp", "parameters": [ { "deprecated": false, "in": "path", "name": "compute_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The session id, minted by the caller, shared with `down`.", "in": "query", "name": "cid", "required": true, "schema": { "description": "The session id, minted by the caller, shared with `down`.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The node to open the terminal on; omit for the first ready one.", "in": "query", "name": "node", "required": false, "schema": { "description": "The node to open the terminal on; omit for the first ready one.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "What to run; omit for the login shell.", "in": "query", "name": "command", "required": false, "schema": { "description": "What to run; omit for the login shell.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The terminal type to claim.", "in": "query", "name": "term", "required": false, "schema": { "default": "xterm-256color", "description": "The terminal type to claim.", "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The terminal width.", "in": "query", "name": "columns", "required": false, "schema": { "default": 80, "description": "The terminal width.", "type": "integer" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "The terminal height.", "in": "query", "name": "rows", "required": false, "schema": { "default": 24, "description": "The terminal height.", "type": "integer" } } ], "responses": { "200": { "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "The up half of an interactive session", "tags": [ "shell" ] } }, "/v1/events": { "get": { "deprecated": false, "description": "Each event's `id:` is the **global sequence**, monotonic. `Last-Event-ID` replays from the event log; the snapshot and the cursor are captured in the same logical order, so there is no gap between reading state and subscribing.\n\nThere is no automatic event GC, so any valid cursor stays resumable.\n\nA slow consumer never blocks a commit: the adapter closes the connection when its local queue overflows and the client reconnects from its last id.\n\nTask stdout/stderr and node bootstrap output are events here. There is no `logs` resource with a second source of truth.\n\nThe schema below is one message's `data:`, not the stream. Its `type` tag discriminates the union; the frame's `event:` field is finer than that tag and is what `types` filters on:\n\n| `event:` | `data.type` |\n|---|---|\n| `compute.ready`, `compute.degraded`, `compute.deleted` | `compute.state` |\n| `compute.abandoned` | `compute.abandoned` |\n| `compute.cost` | `compute.cost` |\n| `node.{state}` \u2014 ten of them | `node.state` |\n| `node.console` | `node.console` |\n| `node.phase` | `node.phase` |\n| `node.metrics` | `node.metrics` |\n| `task.started`, `task.succeeded`, `task.failed`, `task.indeterminate` | `task.state` |\n\n`compute.cost` and `node.metrics` are published rather than recorded: they ride the live feed, carry the last sequence seen rather than one of their own, and never replay.", "operationId": "V1EventsStream", "parameters": [ { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "compute", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "task", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "types", "required": false, "schema": { "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] } }, { "deprecated": false, "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "discriminator": { "mapping": { "compute.abandoned": "#/components/schemas/ComputeAbandoned", "compute.cost": "#/components/schemas/CostEvent", "compute.state": "#/components/schemas/ComputeEvent", "node.console": "#/components/schemas/ConsoleEvent", "node.metrics": "#/components/schemas/MetricEvent", "node.phase": "#/components/schemas/PhaseEvent", "node.state": "#/components/schemas/NodeEvent", "task.state": "#/components/schemas/TaskEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ComputeEvent" }, { "$ref": "#/components/schemas/ComputeAbandoned" }, { "$ref": "#/components/schemas/CostEvent" }, { "$ref": "#/components/schemas/NodeEvent" }, { "$ref": "#/components/schemas/ConsoleEvent" }, { "$ref": "#/components/schemas/PhaseEvent" }, { "$ref": "#/components/schemas/MetricEvent" }, { "$ref": "#/components/schemas/TaskEvent" } ] } } }, "description": "One `data:` payload per message, framed as Server-Sent Events" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" } }, "summary": "Event stream (SSE)", "tags": [ "events" ] } }, "/v1/functions": { "get": { "deprecated": false, "description": "Every function this daemon has been handed, by hash. Uploading the same code twice adds no row.", "operationId": "V1FunctionsList", "parameters": [ { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "cursor", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Function_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" } }, "summary": "List registered functions", "tags": [ "functions" ] } }, "/v1/functions/{sha256}": { "get": { "deprecated": false, "description": "The size, the codec and the name it was registered under \u2014 never the code itself, which is a blob and is fetched as one.", "operationId": "V1FunctionsSha256Read", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Function" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a function's metadata", "tags": [ "functions" ] }, "head": { "deprecated": false, "description": "The SDK calls this before uploading the blob. A function is uploaded **once**, no matter how many tasks call it \u2014 content-addressing is what makes `function` a cheap resource instead of a pickle repeated on every dispatch.", "operationId": "V1FunctionsSha256Exists", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Check whether a function is already registered", "tags": [ "functions" ] }, "put": { "deprecated": false, "description": "The body is the binary envelope (cloudpickle + compression). The server recomputes the hash over the serialized bytes before compression and rejects with `hash_mismatch` if it disagrees with the path.\n\nAccepting cloudpickle is accepting arbitrary code execution. In local single-user mode that is explicit: the caller is the user themselves.", "operationId": "V1FunctionsSha256Register", "parameters": [ { "deprecated": false, "in": "path", "name": "sha256", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "X-Skyward-Function-Name", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } ], "requestBody": { "content": { "application/vnd.skyward.blob": { "schema": { "description": "The bytes themselves \u2014 what they hash to is the name they are stored under.", "format": "binary", "type": "string" } } }, "description": "The serialized function: cloudpickle, then compressed.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Function" } } }, "description": "Already registered \u2014 the upload was a no-op" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Function" } } }, "description": "Document created, URL follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Content does not hash to the name it was given \u2014 `hash_mismatch`" } }, "summary": "Register a function", "tags": [ "functions" ] } }, "/v1/health/dependencies": { "get": { "deprecated": false, "description": "One entry per thing the daemon leans on, keyed by its name. A provider that is unavailable degrades the computes on it; it never fails liveness, because killing a daemon over one marketplace having an afternoon would take every other compute down with it.", "operationId": "V1HealthDependenciesDependencyHealth", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "enum": [ "ok", "unreachable" ], "type": "string" }, "type": "object" } } }, "description": "Request fulfilled, document follows", "headers": {} } }, "summary": "Dependency health", "tags": [ "health" ] } }, "/v1/health/live": { "get": { "deprecated": false, "description": "The process answers. Says nothing about the store or about providers.", "operationId": "V1HealthLiveLive", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Liveness" } } }, "description": "Request fulfilled, document follows", "headers": {} } }, "summary": "Liveness", "tags": [ "health" ] } }, "/v1/health/ready": { "get": { "deprecated": false, "description": "Schema, command writer and initial recovery are usable. Readiness opens once every persisted record has been classified \u2014 it does not wait for new provisioning to finish.", "operationId": "V1HealthReadyReady", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "description": "Request fulfilled, document follows", "headers": {} } }, "summary": "Readiness", "tags": [ "health" ] } }, "/v1/offers": { "get": { "deprecated": false, "description": "Served from the cache. Any provider whose offers have expired is refreshed first \u2014 the TTL belongs to the provider, because a marketplace bundle is gone in minutes while a fixed instance type is not.\n\nA refresh that fails does not empty the catalog: the stale rows are still served and the failure shows up as `last_error` on the provider. A provider being down degrades the answer; it does not erase it.", "operationId": "V1OffersList", "parameters": [ { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "provider", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "kind", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "accelerator", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "min_count", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "min_vram", "required": false, "schema": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "max_price", "required": false, "schema": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Force a refetch even if the cache is still within its TTL.", "in": "query", "name": "refresh", "required": false, "schema": { "default": false, "description": "Force a refetch even if the cache is still within its TTL.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Offer_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Query instance offers", "tags": [ "offers" ] } }, "/v1/provider-kinds": { "get": { "deprecated": false, "description": "Capability negotiation happens here, before anything is created: each kind declares the credentials it needs and how long its offers stay fresh. A kind absent from this list cannot be registered.", "operationId": "V1ProviderKindsList", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ProviderKind" }, "type": "array" } } }, "description": "Request fulfilled, document follows", "headers": {} } }, "summary": "List the provider kinds this build supports", "tags": [ "providers" ] } }, "/v1/providers": { "get": { "deprecated": false, "description": "The accounts this daemon can buy machines from. Credentials are not among the fields returned.", "operationId": "V1ProvidersList", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Provider_" } } }, "description": "Request fulfilled, document follows", "headers": {} } }, "summary": "List registered providers", "tags": [ "providers" ] }, "post": { "deprecated": false, "description": "A provider is a named account, not a kind: two AWS accounts, two Vast keys and two regions can coexist, and a compute refers to the provider it wants by id or name.\n\nCredentials are validated against the kind's `credential_fields` before the row is written, and are never returned by any read path.", "operationId": "V1ProvidersCreate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } }, "description": "Document created, URL follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Register a provider account", "tags": [ "providers" ] } }, "/v1/providers/{provider_id}": { "delete": { "deprecated": false, "description": "Drops the account and its cached offers. Computes already running on it are not touched.", "operationId": "V1ProvidersProviderIdDestroy", "parameters": [ { "deprecated": false, "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Request fulfilled, nothing follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Remove a provider", "tags": [ "providers" ] }, "get": { "deprecated": false, "description": "Accepts an id or a name. Credentials are never included.", "operationId": "V1ProvidersProviderIdRead", "parameters": [ { "deprecated": false, "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a provider", "tags": [ "providers" ] }, "put": { "deprecated": false, "description": "Replaces the account wholesale, credentials included \u2014 there is no partial update, because a half-written credential set is one that fails at launch rather than here. The cached offers are dropped with it.", "operationId": "V1ProvidersProviderIdUpdate", "parameters": [ { "deprecated": false, "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Update a provider account", "tags": [ "providers" ] } }, "/v1/tasks": { "get": { "deprecated": false, "description": "Every call this daemon has been asked to make, newest last. `correlation_id` is how the tasks of one `&`, `gather` or `map` are found together \u2014 it is a field on each of them, not a resource of its own.", "operationId": "V1TasksList", "parameters": [ { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "cursor", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "type": "integer" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "compute", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "state", "required": false, "schema": { "oneOf": [ { "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "timed_out", "indeterminate" ], "type": "string" }, { "type": "null" } ] } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "description": "Groups the tasks of an `&`/`gather`/`map`. A field, not a resource.", "in": "query", "name": "correlation_id", "required": false, "schema": { "description": "Groups the tasks of an `&`/`gather`/`map`. A field, not a resource.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Task_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" } }, "summary": "List tasks", "tags": [ "tasks" ] }, "post": { "deprecated": false, "description": "A task is **one call**: `function` + `args` \u2192 `result`. It is what the SDK's `Future[T]` points at, and its `id` survives retries and SDK restarts.\n\n`dispatch: one` (the `>>` operator) creates a single execution. `dispatch: all` (the `@` operator) freezes the set of `ready` nodes at admission and creates one execution per rank \u2014 a later scale-up does not add executions.\n\nThe task and its first execution are persisted **before** any dispatch to a worker. The worker dedupes on `(task_id, execution_id, args_hash)`.", "operationId": "V1TasksSubmit", "parameters": [ { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "The task this `Idempotency-Key` already created" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "Document created, URL follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Submit a task", "tags": [ "tasks" ] } }, "/v1/tasks/{task_id}": { "delete": { "deprecated": false, "description": "Before `started`, cancellation is guaranteed (CAS + worker ack). After `started` it is best-effort: the execution enters `cancel_requested` and only becomes `cancelled` once the worker confirms it stopped. Without that confirmation the outcome is `indeterminate` \u2014 Python code that may still be running is never declared cancelled.", "operationId": "V1TasksTaskIdCancel", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "Request accepted, processing continues off-line", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" } }, "summary": "Cancel a task", "tags": [ "tasks" ] }, "get": { "deprecated": false, "description": "`state` is **derived** from the executions \u2014 never written alongside them.", "operationId": "V1TasksTaskIdRead", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read a task", "tags": [ "tasks" ] } }, "/v1/tasks/{task_id}/executions": { "get": { "deprecated": false, "description": "One row per attempt, `ordinal`-counted. A retry appears here; it never appears as another task.", "operationId": "V1TasksTaskIdExecutionsListExecutions", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_skyward.shared.schemas.Execution_" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "List the physical attempts", "tags": [ "tasks" ] }, "post": { "deprecated": false, "description": "Retrying **is** creating another physical attempt of the same task \u2014 the `task_id` stays the user's handle. The new execution points `retry_of` at the previous one.\n\nRetrying an `indeterminate` outcome requires `acknowledge_duplication: true`: the system does not know whether the previous execution had side effects, and will not pretend it does.", "operationId": "V1TasksTaskIdExecutionsCreateExecution", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionCreate" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "Request accepted, processing continues off-line", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" } }, "summary": "Create an execution (retry)", "tags": [ "tasks" ] } }, "/v1/tasks/{task_id}/executions/{ordinal}": { "get": { "deprecated": false, "description": "One attempt by its ordinal, including which node took it and what it ended as.", "operationId": "V1TasksTaskIdExecutionsOrdinalGetExecution", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "deprecated": false, "in": "path", "name": "ordinal", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } }, "description": "Request fulfilled, document follows", "headers": {} }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" } }, "summary": "Read one attempt", "tags": [ "tasks" ] } }, "/v1/tasks/{task_id}/result": { "get": { "deprecated": false, "description": "The result survives controller and SDK restarts, and reading does not consume it \u2014 only an explicit purge removes it.\n\n`204` means there is no terminal outcome yet. A non-successful terminal outcome answers `409` with the error code (`task_failed`, `task_indeterminate`, ...).", "operationId": "V1TasksTaskIdResultResult", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } }, { "allowEmptyValue": false, "allowReserved": false, "deprecated": false, "in": "query", "name": "wait", "required": false, "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/vnd.skyward.blob": { "schema": { "type": "string" } } }, "description": "The return value, in the codec the function was written with" }, "204": { "description": "No terminal outcome yet \u2014 ask again" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The write conflicts with what is already here \u2014 `idempotency_conflict`, `lease_held`, `task_failed`, `task_indeterminate`, `duplication_not_acknowledged`" } }, "summary": "Download the result", "tags": [ "tasks" ] } }, "/v1/tasks/{task_id}/stream": { "get": { "deprecated": false, "description": "For a task submitted with `dispatch: stream` \u2014 a generator on the far side. **This request is the dispatch**: nothing starts a streaming task on its own, because the only process that can hold the far end of a stream is the one consuming it.\n\nLength-prefixed msgpack frames: 4 bytes big-endian, then the frame. A frame is an item or a failure, and a failure is the last one \u2014 by the time a generator raises, the caller already has the items before it, and there is no status code left to fail with.\n\nThe body is that framing, so it has no JSON schema: OpenAPI can describe a stream's bytes and not the boundaries a reader has to cut them on.\n\nNot resumable. A dropped stream is a dead stream; submit another task.", "operationId": "V1TasksTaskIdStreamStream", "parameters": [ { "deprecated": false, "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.skyward.frames": { "schema": { "type": "string" } } }, "description": "Length-prefixed msgpack frames, one per item, until the generator ends or fails" }, "400": { "content": { "application/json": { "schema": { "description": "Validation Exception", "examples": [ { "detail": "Bad Request", "extra": {}, "status_code": 400 } ], "properties": { "detail": { "type": "string" }, "extra": { "additionalProperties": {}, "type": [ "null", "object", "array" ] }, "status_code": { "type": "integer" } }, "required": [ "detail", "status_code" ], "type": "object" } } }, "description": "Bad request syntax or unsupported method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No such resource \u2014 `not_found`" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed and unsatisfiable \u2014 `compute_not_accepting`, `capability_mismatch`, `unsupported_provider`, `unsupported_plugin`, `secret_in_definition`" } }, "summary": "Read a streaming task", "tags": [ "tasks" ] } } }, "servers": [ { "url": "/" } ], "tags": [ { "description": "A compute is a set of machines held under one intention: the `spec` you asked for, and the `status` the reconciler observed. It outlives the process that created it \u2014 the SDK's `Compute` is a client holding a lease on this row, not its owner.\n\nResizing is a `PATCH` of the `spec`. Replacing anything else about it is a new **generation**, which keeps the same id and rebuilds the machines under it. The gap between `generation` and `status.observed_generation` is the progress bar, and it is why there is no operation resource to poll.", "name": "computes" }, { "description": "A node is one machine, ranked, as the control plane knows it. Nodes are not created directly: they exist because a compute's `spec.nodes` asked for them, and the reconciler wrote the rows.\n\nA row appears in `requested` **before** the provider is asked for a machine, which is what makes provisioning idempotent \u2014 a machine being bought right now already counts, so the next pass does not buy a second one. A node that died stays listed until the provider confirms the instance is gone.", "name": "nodes" }, { "description": "A task is one call \u2014 `function` + `args` \u2192 `result` \u2014 and it is what an SDK `Future[T]` points at. It is append-only and has exactly one terminal outcome.\n\nAn **execution** is a physical attempt at it. A retry creates another execution, never another task, which is what lets a handle survive the node that died under it. The task's `state` is derived from its executions and never written beside them.", "name": "tasks" }, { "description": "A function is a registered piece of code, named by the hash of its serialized bytes. Registering is content-addressed and therefore idempotent: the same code uploaded twice is one row, however many tasks call it.\n\nThis is the metadata \u2014 size, codec, the name it was registered under. The code itself is a blob.", "name": "functions" }, { "description": "Content addressed by its SHA-256. Code, arguments and results all travel this way rather than inside a task body: the same argument broadcast to a hundred nodes is stored once, and a `PUT` of content already here writes nothing.\n\nReading does not consume. A result read twice is the same bytes twice.", "name": "blobs" }, { "description": "A provider is a named **account**, not a kind of cloud: two AWS accounts, two Vast keys and two regions coexist, and a compute names the one it wants.\n\nCredentials are validated against the kind's declared fields before the row is written, are stored here and nowhere else, and are returned by no read path. `GET /provider-kinds` is the capability negotiation that happens before any of this: a kind absent from that list cannot be registered.", "name": "providers" }, { "description": "The cached hardware catalog \u2014 what each registered account currently sells, normalized into one vocabulary so an `h100` from one provider compares against an `h100` from another.\n\nA cache, not a ledger: a refresh replaces a provider's rows wholesale, because an offer that vanished upstream must vanish here. A refresh that *fails* leaves the stale rows in place, since stale offers beat no offers.", "name": "offers" }, { "description": "One log per compute, and the only place anything observable is written: node output, bootstrap phases, lifecycle transitions and task outcomes all go here. There is no `logs` resource holding a second copy.\n\nIt is a stream rather than a status to poll, and it replays from any cursor that was ever valid \u2014 nothing garbage-collects it, which is what lets a client reconnect and print a bootstrap it was not around to watch.", "name": "events" }, { "description": "Whether the daemon works, and whether what it leans on does. Liveness is about the process; readiness is about being able to serve; dependencies are informational.\n\nA provider being down degrades the computes on it and never fails liveness \u2014 killing a daemon over one marketplace having an afternoon would take every other compute with it.", "name": "health" }, { "description": "A TCP port on a node, reachable from the caller. Each connection is two requests paired by a `cid` the caller mints: a streaming `POST .../up` carrying bytes in, and a `GET .../down` carrying bytes back.\n\nIt takes two because HTTP/1.1 will not carry both directions of a live socket on one request. Neither half is resumable \u2014 a dropped stream is a dropped connection.", "name": "forward" }, { "description": "A pseudo-terminal on a node, in the same two-request shape as forwarding: keystrokes up, paint down, paired by `cid`.\n\nThis reaches the *machine*, not the worker, so it answers while the worker is busy running a training loop. Running code as a task is the other thing, and `POST /tasks` is where it goes.", "name": "shell" }, { "description": "Reading, writing and listing paths on the machines, and running a shell command across them. Every route takes a `node` \u2014 a rank, or `all`.\n\nWrites default to every node, because data a task will read has to be wherever the task lands, and which node that is belongs to the dispatcher. Reads default to one, because four machines hold four files and concatenating them would answer a question nobody asked.", "name": "files" } ] }