{ "components": { "schemas": { "SSHKey": { "type": "object", "required": ["fingerprint", "public_key", "name", "added_at"], "properties": {"fingerprint": {"type": "string"}, "public_key": {"type": "string"}, "name": {"type": "string"}, "added_at": {"type": "string", "format": "date-time"}} }, "ComputeGroup": { "type": "object", "required": ["id", "sweep_id", "kind", "size", "running", "succeeded", "failed"], "properties": {"id": {"type": "string", "description": "Sweep item id, sweep_ followed by the sweep id."}, "sweep_id": {"type": "string"}, "kind": {"type": "string", "enum": ["sweep"]}, "size": {"type": "integer"}, "running": {"type": "integer"}, "succeeded": {"type": "integer"}, "failed": {"type": "integer"}} }, "ComputeItem": { "type": "object", "required": ["id", "type", "name", "gpu", "gpu_count", "gpu_memory_gb", "state", "status_text", "created_at", "started_at", "ended_at", "launched_by", "group", "resource"], "properties": { "id": {"type": "string"}, "type": {"type": "string", "enum": ["instance", "training", "workspace"]}, "name": {"type": "string"}, "gpu": {"type": ["string", "null"]}, "gpu_count": {"type": "integer"}, "gpu_memory_gb": {"type": ["number", "null"]}, "state": {"type": "string", "enum": ["starting", "ready", "running", "recovering", "stopping", "stopped", "paused", "succeeded", "failed", "cancelled"], "description": "paused is frozen training. It holds no compute and lists under history."}, "status_text": {"type": "string"}, "created_at": {"type": "string", "format": "date-time"}, "started_at": {"type": ["string", "null"], "format": "date-time"}, "ended_at": {"type": ["string", "null"], "format": "date-time"}, "launched_by": { "type": "object", "required": ["client", "user_id", "user_name", "api_key_id", "api_key_name"], "properties": { "client": {"type": "string", "enum": ["console", "python-sdk", "cli", "mcp", "claude-code", "codex", "cursor", "api"]}, "user_id": {"type": ["string", "null"]}, "user_name": {"type": ["string", "null"]}, "api_key_id": {"type": ["string", "null"]}, "api_key_name": {"type": ["string", "null"]} } }, "group": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ComputeGroup"}]}, "resource": {"type": "object", "required": ["kind", "id"], "properties": {"kind": {"type": "string", "enum": ["research_workspace", "workload", "sweep"]}, "id": {"type": "string"}}} } }, "ComputeList": { "type": "object", "required": ["items", "next_cursor", "summary"], "properties": { "items": {"type": "array", "items": {"$ref": "#/components/schemas/ComputeItem"}}, "next_cursor": {"type": ["string", "null"]}, "summary": {"type": "object", "required": ["running"], "properties": {"running": {"type": "object", "required": ["instance", "training", "workspace"], "properties": {"instance": {"type": "integer"}, "training": {"type": "integer"}, "workspace": {"type": "integer"}}}}} } }, "AgentEvent": { "type": "object", "additionalProperties": false, "required": [ "source", "event_id", "run_id", "exec_id", "state", "reason", "created_at", "expires_at" ], "properties": { "source": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "event_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "run_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "exec_id": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "blocked", "handled", "expired" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "AgentEventRequest": { "type": "object", "additionalProperties": false, "required": [ "source", "event_id", "run", "command" ], "properties": { "source": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "event_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "run": { "$ref": "#/components/schemas/AgentRunRequest" }, "command": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Explicit driver argv, validated with normal exec bounds. No environment or stdin fields are accepted. Include the run identity in the command as required by your driver." } } }, "AgentReceipt": { "type": "object", "additionalProperties": false, "properties": { "decision": { "type": "string" }, "step_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "external_key": { "type": "string" }, "revision": { "type": "integer" }, "result": { "type": "string", "format": "byte", "maxLength": 349528, "description": "Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused." } }, "required": [ "decision", "step_id", "external_key", "revision" ] }, "AgentResolution": { "type": "object", "additionalProperties": false, "properties": { "step_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "expected_revision": { "type": "integer", "minimum": 1 }, "decision": { "type": "string", "enum": [ "completed", "no_effect", "cancelled" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }, "evidence_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "result": { "type": "string", "format": "byte", "maxLength": 349528, "description": "Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused." } }, "required": [ "step_id", "expected_revision", "decision", "reason", "evidence_digest" ] }, "AgentRun": { "type": "object", "additionalProperties": false, "properties": { "run_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "name": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "version": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "image_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "status": { "type": "string", "enum": [ "active", "blocked", "completed", "cancelled", "expired" ] }, "input": { "type": "string", "format": "byte", "maxLength": 349528, "description": "Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused." }, "result": { "type": "string", "format": "byte", "maxLength": 349528, "description": "Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused." }, "epoch": { "type": "integer", "minimum": 0 } }, "required": [ "run_id", "name", "version", "image_digest", "status", "epoch" ] }, "AgentRunRequest": { "type": "object", "additionalProperties": false, "properties": { "run_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "name": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "version": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "image_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "encoding": { "type": "string", "enum": [ "json-v1" ] }, "input": { "type": "string", "format": "byte", "maxLength": 349528, "description": "Base64 of exact UTF-8 json-v1 bytes, at most 256 KiB decoded. Objects use sorted keys and compact encoding. Nonfinite numbers, duplicate keys and non-JSON values are refused." } }, "required": [ "run_id", "name", "version", "image_digest", "encoding", "input" ] }, "AgentStep": { "type": "object", "additionalProperties": false, "properties": { "checkpoint_id": { "type": "string", "description": "Verified ready or committed state captured for this step's fenced claim. A completed reconciliation must explicitly select matching state when checkpoint recovery is enabled." }, "checkpoint_status": { "type": "string", "enum": ["ready", "committed"], "description": "Publication status of the matching checkpoint candidate. Ready files are verified but do not yet replace committed recovery state." }, "step_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "name": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "version": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 }, "effect": { "type": "string", "enum": [ "external", "pure", "idempotent" ] }, "status": { "type": "string", "enum": [ "started", "completed", "failed", "unknown", "expired" ] }, "revision": { "type": "integer", "minimum": 1 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 3 } }, "required": [ "step_id", "name", "version", "effect", "status", "revision", "attempts" ] }, "AgentStepPage": { "type": "object", "additionalProperties": false, "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStep" }, "maxItems": 100 }, "next_after": { "type": "string" } }, "required": [ "steps" ] }, "Artifact": { "type": "object", "properties": { "manifest_id": { "type": "string" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "sequence": { "type": "integer" }, "manifest": { "type": "object", "description": "Checkpoint manifest metadata. Use outputs/download for produced files." }, "created_at": { "type": "string", "format": "date-time" } } }, "Asset": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "Includes workspace_source for a generated workspace project revision. These copies use their separate included source pool." }, "name": { "type": "string" }, "state": { "type": "string", "description": "Current asset state: importing, ready, failed, deleting or deleted." }, "revision": { "type": "string" }, "sha256": { "type": "string" }, "stored_bytes": { "type": "integer" }, "imported_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "ready_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "export": { "$ref": "#/components/schemas/ConnectionExport" }, "error": { "type": "string", "description": "Value-free terminal query export error. Failed assets remain observable after cleanup, with zero stored bytes once their reservation is released." }, "workspace_source": { "$ref": "#/components/schemas/WorkspaceSourceAlias" } } }, "AssetImportRequest": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "github", "huggingface", "url", "connection_query" ] }, "url": { "type": "string", "description": "Public HTTPS direct download URL for kind=url. Private downloads use signed links." }, "repo": { "type": "string", "description": "owner/name for GitHub or a Hugging Face dataset. Matching HTTPS repository URLs are also accepted." }, "ref": { "type": "string", "maxLength": 255, "default": "main", "description": "Repository revision. Omitted or empty selects main. Carriage returns and newlines are rejected." }, "files": { "type": [ "array", "null" ], "maxItems": 100, "items": { "type": "string" }, "description": "Hugging Face dataset file patterns. Omitted selects recognized data file extensions. GitHub imports include the repository archive." }, "token": { "type": "string", "writeOnly": true, "description": "Optional GitHub or Hugging Face credential. Rejected for URL imports." }, "connection_id": { "type": "string", "description": "Database connection name or ID for connection_query. Requires read or readwrite scope and an active pinned credential." }, "sql": { "type": "string", "maxLength": 60000, "description": "One SELECT or WITH statement, executed in a read-only transaction with a ten-minute timeout." }, "format": { "type": "string", "enum": [ "parquet", "csv" ], "default": "parquet" }, "branch": { "type": "string", "description": "Optional Neon branch assertion. Must match the branch already verified on the connection." }, "reuse": { "type": "boolean", "default": false, "description": "Reuse an eligible ready export for this tenant, connection, exact SQL apart from outer whitespace, branch and format from the last 24 hours." } }, "description": "The server requires the source appropriate to kind. Import limits are deployment specific and returned by GET /v1/assets. Archives cannot contain links, special files, unsafe paths or more than 10000 files. Connection queries produce data.parquet or data.csv inside a normal input asset, with a 5 GB and 50 million row limit. Existing tenant storage quota also applies. Credentials remain on the control plane." }, "AssetList": { "type": "object", "properties": { "assets": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/Asset" } }, "max_import_bytes": { "type": "integer", "description": "Maximum source bytes for one import or upload." }, "storage_quota_bytes": { "type": "integer" }, "staged_bytes": { "type": "integer" }, "stored_bytes": { "type": "integer", "description": "Ordinary asset bytes, excluding generated workspace source copies." }, "billing_enabled": { "type": "boolean", "const": false }, "workspace_source_storage": { "$ref": "#/components/schemas/WorkspaceSourceStorage" }, "upload_idempotency": { "type": "boolean", "description": "True when uploads support persistent request keys bound to exact content hashes. Clients requiring durable upload receipts must check this capability before sending bytes." } }, "required": [ "assets", "max_import_bytes", "storage_quota_bytes", "staged_bytes", "stored_bytes", "billing_enabled" ] }, "BenchmarkCell": { "type": "object", "properties": { "gpu_family": { "type": "string" }, "batch_size": { "type": "integer" }, "region": { "type": "string" }, "repetition": { "type": "integer" }, "budget_usd": { "type": "number", "deprecated": true, "description": "Deprecated compatibility field. Customer spending limits are not enforced." }, "workload_id": { "type": "string" }, "workload_url": { "type": "string" }, "status": { "type": "string" }, "spend_usd": { "type": "number", "description": "Posted workload ledger charges. Active and unsettled usage may be absent." }, "wall_seconds": { "type": [ "number", "null" ], "description": "Elapsed time from admission through terminal status or report time." }, "unit_metrics": { "$ref": "#/components/schemas/UnitMetrics" }, "units_per_second": { "type": [ "number", "null" ], "description": "Observed completed units divided by wall_seconds. Missing observations are not estimated." } } }, "BenchmarkMatrix": { "type": "object", "additionalProperties": false, "required": [ "gpu_families", "batch_sizes", "regions", "repetitions" ], "properties": { "gpu_families": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string" } }, "batch_sizes": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, "regions": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "string" } }, "repetitions": { "type": "integer", "minimum": 1, "maximum": 64 } } }, "BenchmarkReport": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "budget_usd": { "type": "number", "deprecated": true, "description": "Deprecated compatibility field. Customer spending limits are not enforced." }, "spend_usd": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkCell" } } } }, "BenchmarkRequest": { "type": "object", "additionalProperties": false, "required": [ "workload", "matrix" ], "properties": { "workload": { "$ref": "#/components/schemas/WorkloadPayload" }, "matrix": { "$ref": "#/components/schemas/BenchmarkMatrix" }, "budget_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true } } }, "CheckpointSummary": { "type": "object", "properties": { "manifest_id": { "type": "string" }, "generation": { "type": "integer" }, "sequence": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "description": "Original commit time of the latest useful recovery checkpoint. Independent of event pagination and unchanged by commit retries or artifact-only uploads." } } }, "Continuity": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "", "checkpointed", "restartable", "ephemeral" ], "description": "Top-level empty/omitted defaults to checkpointed. A stage with omitted mode inherits workload mode and resume behavior. Checkpoint paths inherit separately." }, "resume_on_interruption": { "type": "boolean", "default": true, "description": "Omission defaults to true. Explicit false disables resumption. Per-stage mode omission inherits workload mode and resume behavior." }, "checkpoint_paths": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Literal normalized paths relative to the code folder, with at most 512 UTF-8 bytes per path. Select files or folders containing recovery state. Empty or omitted at workload level defaults new submissions to [\"state\"]. The runner exposes this folder as NODUS_CHECKPOINT_DIR. Only explicitly selected paths are saved, not installed dependencies elsewhere in the code folder. Empty or omitted at stage level inherits workload paths, a nonempty list overrides them, and [\".\"] explicitly selects the whole folder. Absolute paths, traversal, backslashes, colons, control characters and the .nodus subtree are rejected. Missing paths are skipped without widening the selection. Dependencies outside selected paths must be recreated by the image or command. Final result files are independent. Framework shortcuts apply workload-level paths to their generated stages. Stage-specific paths alongside a framework shortcut are not supported, use explicit stages instead." }, "integration": { "type": "string", "enum": [ "", "none", "auto", "hf-trainer-v1" ], "description": "Application save and resume integration. New submissions leave application checkpoint preparation disabled unless auto or hf-trainer-v1 is explicitly selected. Omission and none preserve the original source and application-managed checkpoint behavior. A stage inherits an explicit workload selection when omitted. Imported source alone does not enable preparation. auto attempts the supported framework adapter and otherwise runs the original command with application-managed checkpoints. hf-trainer-v1 requires supported Hugging Face Trainer preparation and runtime validation. Explicit managed selections require execution-v2, enabled preparation and source.asset_id. Previously accepted submissions keep their original selection. Prepared source does not itself prove that application state has been saved or recovered." } } }, "CostBreakdown": { "type": "object", "properties": { "runtime_hours": { "type": "number" }, "provision_hours": { "type": "number" }, "billed_hours": { "type": "number" }, "billing_increment_min": { "type": "number" }, "compute_usd": { "type": "number" }, "expected_reclaims": { "type": "number" }, "lost_hours_per_reclaim": { "type": "number" }, "reclaim_usd": { "type": "number" }, "interruption_usd": { "type": "number" }, "reserve_usd": { "type": "number" }, "total_usd": { "type": "number" } } }, "CustomerFallbackBranch": { "type": "object", "properties": { "failure_class": { "type": "string" }, "expected_recovery_hours": { "type": "number" }, "expected_cost_usd": { "type": [ "number", "null" ], "description": "Estimated fallback cost, or null when a trustworthy total estimate is unavailable." } } }, "CustomerLedgerEntry": { "type": "object", "properties": { "id": { "type": "string" }, "correlation_id": { "type": "string" }, "entry_type": { "type": "string" }, "debit_usd": { "type": "number" }, "credit_usd": { "type": "number" }, "currency": { "type": "string" }, "evidence": { "type": [ "object", "null" ], "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" } } }, "CustomerRejectedOffer": { "type": "object", "properties": { "reason": { "type": "string" } } }, "CustomerRouteSummary": { "type": "object", "properties": { "fit_class": { "type": "string" }, "compute_class": { "type": "string" }, "resources": { "$ref": "#/components/schemas/ResourceAttributes" }, "memory_gb": { "type": "number" }, "offer_id": { "type": "string" }, "price_usd_hour": { "type": "number" }, "interruptible": { "type": "boolean" }, "region": { "type": "string" }, "expected_cost_usd": { "type": [ "number", "null" ], "description": "Estimated total cost, or null when a trustworthy total estimate is unavailable." }, "expected_hours": { "type": [ "number", "null" ], "description": "Estimated completion time in hours, or null when a trustworthy runtime estimate is unavailable." }, "remaining_budget_usd": { "type": "number" }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/CostBreakdown" }, { "type": "null" } ] }, "score_breakdown": { "$ref": "#/components/schemas/ScoreBreakdown" }, "fallback_graph": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CustomerFallbackBranch" } }, "rejected": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CustomerRejectedOffer" } } } }, "EmptyRequest": { "type": "object", "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "LiveLogPage": { "type": "object", "required": [ "chunks", "next_cursor", "truncated" ], "properties": { "chunks": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "id", "stage_id", "generation", "text" ], "properties": { "id": { "type": "integer" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "text": { "type": "string" } } }, { "$ref": "#/components/schemas/DistributedLogChunk" } ] } }, "next_cursor": { "type": "string" }, "truncated": { "type": "boolean" }, "group_id": { "type": "string" }, "member_id": { "type": "string" }, "expired": { "type": "boolean" } } }, "Meter": { "type": "object", "properties": { "settled_usd": { "type": "number" }, "accruing_usd": { "type": "number" }, "accruing_rate_usd_hour": { "type": "number" }, "total_now_usd": { "type": "number" }, "as_of": { "type": "string", "format": "date-time" }, "final_charge_usd": { "type": "number", "minimum": 0, "description": "Immutable aggregate lifetime compute charge for a terminal workload. Present only after every customer usage clock is settled and complete initial compute cost coverage is available across the workload scope. This total is independent of the current billing month. Retaining files can continue to incur separate usage charges, which are excluded from this fixed compute total." }, "charge_state": { "type": "string", "enum": ["estimated", "final"], "description": "Compute charge finality for workloads using metered pricing. Estimated means compute usage is still accruing, terminal usage is still settling, or required initial compute cost coverage is incomplete. Final means final_charge_usd is frozen. Retained-file usage can continue after compute is final. Historical workload contracts may omit this field." }, "compute_settled_usd": { "type": "number", "default": 0, "description": "Settled compute charges in this billing period." }, "platform_fee_settled_usd": { "type": "number", "default": 0, "description": "Settled platform fees in this billing period." }, "subscription_settled_usd": { "type": "number", "default": 0, "description": "Settled subscription charges in an account meter. Zero in workload meters." }, "storage_settled_usd": { "type": "number", "default": 0, "description": "Settled saved-file charges earned in this UTC billing month in an account meter. Already included in settled_usd. Zero in workload and workspace compute-session meters." }, "model_settled_usd": { "type": "number", "default": 0, "description": "Settled managed model charges in this billing period in an account meter. Already included in settled_usd. Zero in workload and workspace compute-session meters." }, "shared_settled_usd": { "type": "number", "default": 0, "description": "Settled shared service charges in this billing period in an account meter. Already included in settled_usd. Zero in workload and workspace compute-session meters." }, "compute_accruing_usd": { "type": "number", "default": 0, "description": "Compute charges accruing at as_of." }, "platform_fee_accruing_usd": { "type": "number", "default": 0, "description": "Platform fees accruing at as_of." } } }, "Outcome": { "type": "object", "properties": { "max_cost_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "complete_by": { "type": "string", "description": "RFC3339 completion deadline, or empty/omitted for none. Example: 2026-12-01T18:00:00Z." } } }, "Output": { "type": "object", "properties": { "name": { "type": "string" }, "stage_id": { "type": "string" }, "sha256": { "type": "string" }, "bytes": { "type": "integer" }, "download": { "type": "string" }, "sink_state": { "type": "string", "enum": [ "pending", "loading", "loaded", "failed" ] }, "sink_rows": { "type": "integer", "minimum": 0 }, "sink_error": { "type": "string" }, "group_id": { "type": "string", "description": "Nodus distributed group that owns this verified result, when applicable." }, "member_id": { "type": "string", "description": "Nodus member that owns this result. Select this member when downloading same-named shards." } }, "required": [ "name", "stage_id", "sha256", "bytes", "download" ] }, "Policy": { "type": "object", "properties": { "data_regions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Allowed placement regions. SDK data_regions maps here. Empty/omitted imposes no region filter." }, "secret_refs": { "type": "array", "maxItems": 32, "items": { "type": "string" }, "description": "Tenant secret references pinned at admission and delivered only to the authorized execution." }, "egress_allow": { "type": "array", "maxItems": 128, "items": { "type": "string" }, "description": "HTTPS hostnames added to the connection host allowlist. Isolated execution blocks all other network access." } } }, "Requirements": { "type": "object", "properties": { "optimization": { "type": "string", "enum": [ "", "automatic", "lowest_cost", "lower_cost", "balanced", "faster", "fastest" ], "deprecated": true, "description": "Optimization tiers are not currently supported. Omit this field. New workloads and stages use automatic routing. Accepted legacy values remain compatible but do not change routing for new submissions. Existing workloads retain their persisted settings. Automatic routing uses qualified runtime-cost estimates when all eligible configurations have comparable measurements. Otherwise it provisionally ranks by hourly price with a temporary preference for compatible configurations without a recent matching startup failure. Compatibility, spending and independent price limits remain enforced. This does not guarantee the lowest total job cost or shortest runtime." }, "disk_gb": { "type": "number", "minimum": 0, "description": "Finite nonnegative disk capacity requirement in GB. An omitted or zero stage value inherits the workload requirement." }, "vcpus": { "type": "number", "minimum": 0, "description": "Finite nonnegative CPU capacity requirement. An omitted or zero stage value inherits the workload requirement." }, "model": { "type": "string" }, "compute_class": { "type": "string", "enum": [ "", "vm", "accelerator" ], "description": "Empty or omitted defaults to accelerator. Customer workloads currently use GPU infrastructure. The vm value remains accepted for compatibility and does not establish an available customer offering." }, "dataset_bytes": { "type": "integer", "minimum": 0 }, "peak_memory_gb": { "type": "number", "minimum": 0, "description": "Finite nonnegative memory requirement per GPU in GB. Memory is not pooled across devices. Zero or omission lets Nodus infer memory. The Python SDK requires a positive value when explicitly supplied." }, "notes": { "type": "string" }, "gpu": { "type": "string", "description": "Optional required GPU model family, such as H100. Memory is specified separately. Nodus does not substitute another model." }, "expected_runtime_hours": { "type": "number", "deprecated": true, "description": "Legacy wire compatibility only. Customers do not need to supply a runtime estimate. It does not determine spending admission." }, "gpu_count": { "type": "integer", "enum": [ 1, 2, 4, 8 ], "description": "Exact number of GPUs on one machine. Omission defaults to one GPU or inherits the workload count for a stage. Never split across machines." }, "gpu_interconnect": { "type": "string", "enum": [ "", "any" ], "description": "No interconnect guarantee. Requests for NVLink or NVSwitch are rejected until topology can be verified." }, "node_count": { "type": "integer", "minimum": 1, "maximum": 256, "description": "Exact machines required. Omission defaults to one or inherits the workload count for a stage. Multi-machine submissions currently return distributed_training_unavailable before allocation. The schema bound is not a qualified production capacity." }, "distribution": { "$ref": "#/components/schemas/TrainingDistribution", "description": "Explicit framework and process topology. Submissions containing this field currently return distributed_training_unavailable before allocation." }, "total_gpu_count": { "type": "integer", "minimum": 1, "maximum": 2048, "description": "Exact total GPUs requested across an allocation. Cannot be combined with node_count or gpu_count. Omission preserves existing per-machine sizing. This expresses resource demand without selecting a supplier or changing the training command. Multi-GPU total requests currently return distributed_training_unavailable before allocation. The schema maximum is not a production capacity guarantee." } }, "allOf": [ { "not": { "required": [ "total_gpu_count" ], "anyOf": [ { "required": [ "node_count" ] }, { "required": [ "gpu_count" ] } ] } }, { "if": { "not": { "required": [ "total_gpu_count" ], "properties": { "total_gpu_count": { "minimum": 2 } } } }, "then": { "properties": { "distribution": { "required": [ "processes_per_node" ], "properties": { "processes_per_node": { "minimum": 1 } } } } } } ] }, "ResourceAttributes": { "type": "object", "properties": { "vcpus": { "type": "number" }, "host_memory_gb": { "type": "number" }, "device_memory_gb": { "type": "number" }, "disk_gb": { "type": "number" }, "network_gbps": { "type": "number" }, "accelerator": { "type": "string" }, "gpu_count": { "type": "integer", "minimum": 0, "description": "Number of GPUs in this single-machine allocation." } } }, "RoutingPlacement": { "type": "object", "properties": { "workload_id": { "type": "string" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "sku": { "type": "string" }, "fit_class": { "type": "string" }, "region": { "type": "string" }, "compute_class": { "type": "string" }, "continuity_mode": { "type": "string" }, "interruptible": { "type": "boolean" }, "placement": { "type": "string" }, "provision_attempts": { "type": "integer" }, "provisioned_at": { "type": "string", "format": "date-time" }, "running_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "boot_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "boot_ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "price_usd_hour": { "type": "number" }, "predicted_cost_usd": { "type": "number" }, "predicted_hours": { "type": "number" }, "predicted_boot_seconds": { "type": "number" }, "predicted_interrupt_rate": { "type": "number" }, "actual_cost_usd": { "description": "Reserved optional compatibility field. Customer responses omit placement-level charges. Use the workload meter and Insights for aggregate recorded spend.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "actual_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "checkpoints": { "type": "integer" }, "checkpoint_bytes": { "type": "integer" }, "output_bytes": { "type": "integer" }, "restore_bytes": { "type": "integer" }, "restored_from": { "type": "string" }, "checkpoint_seconds": { "type": "number" }, "interrupted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "interrupt_trigger": { "type": "string" }, "lost_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recovery_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "superseded_by": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "outcome": { "type": "string" } } }, "Sandbox": { "type": "object", "required": [ "id", "state", "envelope", "created_at", "updated_at", "last_activity_at", "cost_usd", "url" ], "properties": { "id": { "type": "string" }, "state": { "$ref": "#/components/schemas/SandboxState" }, "envelope": { "$ref": "#/components/schemas/SandboxEnvelope" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_activity_at": { "type": "string", "format": "date-time" }, "terminal_at": { "type": [ "string", "null" ], "format": "date-time" }, "cost_usd": { "type": "number", "minimum": 0, "description": "Customer cost recorded for this sandbox." }, "charge_state": { "type": "string", "enum": ["estimated", "final"], "description": "Present for metered sandboxes. A terminal sandbox remains estimated while required cost records are unavailable. Show Finalizing cost until final. Historical contracts omit this field." }, "final_charge_usd": { "type": "number", "minimum": 0, "description": "Immutable aggregate lifetime compute charge once charge_state is final. This amount is independent of current-month readings and excludes ongoing retained-file usage. Retaining files can continue to incur separate usage charges after compute is final. Omitted while the compute cost is finalizing." }, "network_usage": { "type": "object", "description": "Last reported cumulative proxied HTTP and TLS stream bytes across sandbox generations. A lost host can leave its final unreported bytes unknown. These counters do not determine customer charges.", "required": [ "sent_bytes", "received_bytes" ], "properties": { "sent_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "received_bytes": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "url": { "type": "string", "format": "uri", "description": "Console URL for this sandbox." }, "failure": { "type": "object", "description": "Recorded cause and recovery guidance for a failed sandbox. Omitted for other states.", "required": [ "code", "message", "fix" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fix": { "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Nonfatal warnings, including bootstrap_failed when the setup command fails." }, "setup_state": { "type": "string" }, "setup_failure": { "type": "string" }, "last_successful_save_at": { "type": "string", "format": "date-time", "description": "Last verified nonempty saved project. Absence does not imply saved application progress." }, "startup": { "$ref": "#/components/schemas/SandboxStartup" }, "started_at": {"type": "string", "format": "date-time", "description": "First observed tool readiness for the current direct workspace compute session. Absent while starting and on legacy sessions without this timestamp. This is separate from creation time and changes with a replacement session."} } }, "SandboxBootstrap": { "type": "object", "additionalProperties": false, "required": [ "repo" ], "properties": { "repo": { "type": "string", "description": "Connected GitHub repository as owner/name. Credentials and URLs are not accepted." }, "ref": { "type": "string", "description": "Optional branch name or refs/tags/name. Defaults to the repository default branch." }, "setup": { "type": "string", "maxLength": 8192, "description": "Shell setup command recorded as a sandbox execution. A managed template requires successful setup before customer commands. Legacy images retain their existing warning behavior." }, "dotfiles": { "type": "string", "description": "Optional connected GitHub dotfiles repository as owner/name. Its install.sh runs before setup." } }, "description": "Preview repository bootstrap. Requires github.com in the egress allowlist. Checkout is placed in /workspace. The installation credential is never supplied to customer processes." }, "SandboxContinuity": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "snapshotted", "ephemeral" ], "default": "snapshotted", "description": "Whether Nodus periodically saves filesystem recovery state." }, "interval_s": { "type": "integer", "minimum": 1, "description": "Snapshot interval in seconds. Omit for ephemeral sandboxes." } }, "additionalProperties": false }, "SandboxCreateRequest": { "additionalProperties": false, "description": "Creates a sandbox, or reconnects to an active name within the authenticated account. New sandboxes require an image. Omitted fields on a reconnect preserve existing configuration.", "properties": { "bootstrap": { "$ref": "#/components/schemas/SandboxBootstrap" }, "continuity": { "$ref": "#/components/schemas/SandboxContinuity" }, "from_snapshot": { "type": "string", "description": "Optional Nodus snapshot identifier used to restore a compatible sandbox." }, "image": { "type": "string", "description": "Container image reference. Nodus resolves tags to an immutable Linux amd64 digest before placement." }, "lifecycle": { "$ref": "#/components/schemas/SandboxLifecycle" }, "name": { "type": "string", "maxLength": 128, "description": "Optional stable customer label used when listing sandboxes." }, "outcome": { "$ref": "#/components/schemas/SandboxOutcome" }, "policy": { "$ref": "#/components/schemas/SandboxPolicy" }, "requirements": { "$ref": "#/components/schemas/SandboxRequirements" }, "reservation": { "$ref": "#/components/schemas/SandboxReservation" }, "secrets": { "type": "array", "maxItems": 32, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }, "description": "Tenant secret names bound to current versions at boot. The NODUS_ prefix is reserved. Values are available to commands as environment variables and files in NODUS_SECRETS_DIR." }, "service": { "$ref": "#/components/schemas/SandboxService" }, "stuck_after_s": { "type": "integer", "minimum": 30, "maximum": 604800, "description": "Alert after an active command produces no output for this many seconds. Defaults to 1800. Alerts do not stop the command." }, "wake": { "type": "string", "enum": [ "auto", "instant", "fast", "cheap" ], "default": "auto", "description": "Startup preference expressed as an outcome. Nodus still chooses the infrastructure." }, "workspace": { "$ref": "#/components/schemas/WorkspaceSelection" }, "source": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string" }, "asset_id": { "type": "string" }, "cache": { "type": "boolean", "default": false, "description": "Opt in to verified image layer caching within this team and selected execution region. Retained storage stays attributed to the first materializing sandbox at the configured workspace storage rate. Cache misses use the image registry." } }, "additionalProperties": false }, "connections": { "type": "array", "maxItems": 1, "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,127}$" }, "description": "One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode." }, "template": { "type": "string", "enum": [ "nodus:agent-tools-v1" ], "description": "Qualified managed environment. Availability is returned by sandbox templates. Omit for name-only reconnect or a custom image." }, "network_permissions": { "type": "array", "items": { "type": "string", "enum": [ "github", "python_packages", "node_packages", "openai", "anthropic" ] }, "uniqueItems": true }, "setup": { "type": "string", "maxLength": 8192, "description": "Managed template setup command. Customer commands wait for successful setup." } }, "required": null, "type": "object" }, "SandboxEnvelope": { "properties": { "bootstrap": { "$ref": "#/components/schemas/SandboxBootstrap" }, "continuity": { "type": "object", "additionalProperties": true }, "from_snapshot": { "type": "string" }, "lifecycle": { "$ref": "#/components/schemas/SandboxLifecycle" }, "name": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/SandboxOutcome" }, "policy": { "$ref": "#/components/schemas/SandboxPolicy" }, "profile": { "type": "string", "deprecated": true, "readOnly": true, "description": "Historical profile retained on previously admitted sandboxes. New sandbox requests cannot select a profile." }, "requirements": { "type": "object", "additionalProperties": true }, "reservation": { "type": "object", "additionalProperties": true }, "secrets": { "type": "array", "maxItems": 32, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }, "description": "Tenant secret names bound to current versions at boot. The NODUS_ prefix is reserved. Values are available to commands as environment variables and files in NODUS_SECRETS_DIR." }, "service": { "$ref": "#/components/schemas/SandboxService" }, "source": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string" }, "asset_id": { "type": "string" }, "cache": { "type": "boolean", "default": false, "description": "Opt in to verified image layer caching within this team and selected execution region. Retained storage stays attributed to the first materializing sandbox at the configured workspace storage rate. Cache misses use the image registry." } }, "additionalProperties": false }, "stuck_after_s": { "type": "integer", "minimum": 30, "maximum": 604800, "description": "Alert after an active command produces no output for this many seconds. Defaults to 1800. Alerts do not stop the command." }, "workspace": { "$ref": "#/components/schemas/WorkspaceSelection" }, "connections": { "type": "array", "maxItems": 1, "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,127}$" }, "description": "One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode." } }, "required": [ "source", "requirements", "outcome", "policy", "lifecycle", "reservation", "continuity" ], "type": "object" }, "SandboxError": { "type": "object", "required": [ "code", "message", "fix", "url" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fix": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "SandboxExec": { "type": "object", "required": [ "id", "sandbox_id", "spec", "state", "created_at", "updated_at", "output_sequence", "stdout_bytes", "stderr_bytes" ], "properties": { "id": { "type": "string" }, "sandbox_id": { "type": "string" }, "spec": { "$ref": "#/components/schemas/SandboxExecRequest" }, "state": { "$ref": "#/components/schemas/SandboxExecState" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "exit_code": { "type": [ "integer", "null" ], "description": "Process exit code when known. A completed process can have a nonzero exit code." }, "failure_code": { "type": "string", "description": "Failure to start or maintain execution, separate from a process exit code." }, "output_sequence": { "type": "integer", "minimum": 0 }, "stdout_bytes": { "type": "integer", "minimum": 0 }, "stderr_bytes": { "type": "integer", "minimum": 0 }, "final_output_sequence": { "type": [ "integer", "null" ], "minimum": 0 }, "cancel_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancel_reason": { "type": "string" } } }, "SandboxExecRequest": { "type": "object", "required": [ "command" ], "properties": { "command": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Process argument vector. No shell parsing is performed." }, "cwd": { "type": "string", "description": "Optional canonical absolute POSIX working directory." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Nonsecret environment values. Values equal to any retained tenant secret are rejected. Use sandbox secrets for confidential values." }, "timeout_s": { "type": "integer", "minimum": 1, "description": "Process timeout no greater than the sandbox maximum lifetime." }, "stdin": { "type": "boolean", "default": false, "description": "Enable framed stdin writes for this process." }, "tty": { "type": "boolean", "default": false, "description": "Allocate a controlling terminal with merged stdout and stderr. Requires stdin and explicit rows and cols." }, "rows": { "type": "integer", "minimum": 1, "maximum": 4096 }, "cols": { "type": "integer", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false }, "SandboxExecState": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled", "lost" ] }, "SandboxLifecycle": { "type": "object", "properties": { "idle_timeout_s": { "type": "integer", "minimum": 1, "default": 300, "description": "Idle seconds before the configured action." }, "max_lifetime_s": { "type": "integer", "minimum": 1, "default": 86400, "description": "Maximum sandbox lifetime in seconds." }, "on_idle": { "type": "string", "enum": [ "suspend", "terminate" ], "default": "suspend", "description": "Action after the idle timeout." } }, "additionalProperties": false }, "SandboxMetricObservation": { "type": "object", "properties": { "sequence": { "type": "integer" }, "generation": { "type": "integer" }, "observed_at": { "type": "string", "format": "date-time" }, "cpu_seconds": { "type": [ "number", "null" ] }, "rss_bytes": { "type": [ "integer", "null" ] }, "disk_used_bytes": { "type": [ "integer", "null" ] }, "egress_sent_bytes": { "type": [ "integer", "null" ] }, "egress_received_bytes": { "type": [ "integer", "null" ] }, "active_execs": { "type": [ "integer", "null" ] } }, "required": [ "sequence", "generation", "observed_at", "cpu_seconds", "rss_bytes", "disk_used_bytes", "egress_sent_bytes", "egress_received_bytes", "active_execs" ], "description": "Server timestamp and current runtime generation. CPU is a cumulative runtime counter. RSS sums guest process resident pages and can double count shared pages. Disk measures regular file logical bytes under the workspace. Missing or failed measurements remain null." }, "SandboxMetricReport": { "type": "object", "properties": { "latest": { "anyOf": [ { "$ref": "#/components/schemas/SandboxMetricObservation" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxMetricObservation" } }, "rollup_24h": { "$ref": "#/components/schemas/SandboxMetricRollup" }, "last_output_at": { "type": [ "string", "null" ], "format": "date-time" }, "meter": { "$ref": "#/components/schemas/Meter" } }, "required": [ "latest", "history", "rollup_24h", "last_output_at", "meter" ] }, "SandboxMetricRollup": { "type": "object", "properties": { "samples": { "type": "integer" }, "peak_rss_bytes": { "type": [ "number", "null" ] }, "average_rss_bytes": { "type": [ "number", "null" ] }, "peak_disk_used_bytes": { "type": [ "number", "null" ] }, "peak_active_execs": { "type": [ "number", "null" ] }, "cpu_seconds": { "type": [ "number", "null" ] }, "egress_sent_bytes": { "type": [ "number", "null" ] }, "egress_received_bytes": { "type": [ "number", "null" ] } }, "required": [ "samples", "peak_rss_bytes", "average_rss_bytes", "peak_disk_used_bytes", "peak_active_execs", "cpu_seconds", "egress_sent_bytes", "egress_received_bytes" ], "description": "Measured 24 hour peaks and average RSS. CPU and egress are differences between the oldest and newest available samples within each runtime generation. No estimate fills gaps or single-sample intervals." }, "SandboxOutcome": { "type": "object", "properties": { "max_cost_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "complete_by": { "type": "string", "format": "date-time", "description": "Optional RFC3339 deadline for the sandbox." } }, "additionalProperties": false }, "SandboxOutputFrame": { "type": "object", "required": [ "sequence", "stream", "offset", "data", "created_at" ], "properties": { "sequence": { "type": "integer", "minimum": 1 }, "stream": { "type": "string", "enum": [ "stdout", "stderr" ] }, "offset": { "type": "integer", "minimum": 0 }, "data": { "type": "string", "format": "byte", "description": "Base64 encoded output bytes." }, "created_at": { "type": "string", "format": "date-time" } } }, "SandboxOutputPage": { "type": "object", "required": [ "frames", "next_sequence", "last_sequence", "state", "done", "complete" ], "properties": { "frames": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxOutputFrame" } }, "next_sequence": { "type": "integer", "minimum": 0, "description": "Cursor for the next read." }, "last_sequence": { "type": "integer", "minimum": 0 }, "final_sequence": { "type": [ "integer", "null" ], "minimum": 0 }, "state": { "$ref": "#/components/schemas/SandboxExecState" }, "done": { "type": "boolean", "description": "True when the execution is terminal." }, "complete": { "type": "boolean", "description": "True when the page reaches the final output sequence without a gap." } } }, "SandboxPolicy": { "type": "object", "properties": { "data_regions": { "type": "array", "items": { "type": "string" }, "description": "Allowed placement regions. Empty or omitted imposes no region filter." }, "network": { "type": "string", "enum": [ "deny", "allowlist" ], "default": "deny", "description": "Outbound network policy." }, "egress_allow": { "type": "array", "items": { "type": "string" }, "description": "Exact DNS hostnames allowed when network is allowlist." }, "secret_refs": { "type": "array", "items": { "type": "string" }, "description": "Secret names or sec_ IDs pinned at admission and delivered as NODUS_SECRET_. Rotation, revocation and recovery preserve the admitted version." } }, "additionalProperties": false }, "SandboxRequirements": { "type": "object", "properties": { "compute_class": { "type": "string", "enum": [ "vm", "accelerator" ], "description": "Infrastructure class. Omission selects vm (CPU) for a new sandbox and preserves the stored class when reconnecting by name. CPU sandboxes require a preview deployment with compatible capacity. Existing GPU sandbox clients explicitly request accelerator." }, "gpu": { "type": "string", "description": "Optional required GPU model family. Nodus matches compatible infrastructure without exposing supplier SKUs." }, "vcpus": { "type": "number", "minimum": 0, "description": "Required virtual CPUs. Zero or omission uses the server default." }, "peak_memory_gb": { "type": "number", "minimum": 0, "description": "Required memory in GB. Zero or omission uses the server default." }, "disk_gb": { "type": "number", "minimum": 0, "description": "Required disk capacity in GB. Zero or omission uses the server default." }, "dataset_bytes": { "type": "integer", "minimum": 0, "description": "Optional input data size used for infrastructure matching." }, "model": { "type": "string", "description": "Optional workload fit signal." }, "notes": { "type": "string", "description": "Optional workload fit notes." } }, "additionalProperties": false }, "SandboxReservation": { "type": "object", "properties": { "wake_slo_ms": { "type": "integer", "minimum": 1, "description": "Requested wake service level in milliseconds." }, "max_idle_s": { "type": "integer", "minimum": 0, "description": "Maximum idle duration retained by the reservation." }, "min_ready": { "type": "integer", "minimum": 0, "description": "Minimum ready capacity." }, "max_concurrent": { "type": "integer", "minimum": 1, "default": 1, "description": "Maximum concurrent sandboxes for this reservation." }, "release": { "type": "string", "enum": [ "auto", "hold" ], "default": "auto", "description": "Whether idle capacity is automatically released." }, "cron": { "type": "string", "description": "Optional five-field cron expression for planned readiness." } }, "additionalProperties": false }, "SandboxService": { "type": "object", "required": [ "command", "port", "health_path" ], "properties": { "command": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "port": { "type": "integer", "minimum": 1024, "maximum": 65535, "description": "Guest loopback HTTP port. Port 18080 is reserved." }, "health_path": { "type": "string", "description": "Absolute HTTP health path. Successful 2xx health response is required before serving requests." } } }, "SandboxState": { "type": "string", "enum": [ "creating", "ready", "running", "idle", "suspended", "resuming", "recovering", "terminated", "failed", "freezing", "frozen" ] }, "SandboxStdinReceipt": { "type": "object", "required": [ "sequence", "bytes", "eof", "created_at" ], "properties": { "sequence": { "type": "integer", "minimum": 1 }, "bytes": { "type": "integer", "minimum": 0 }, "eof": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "SandboxStdinRequest": { "type": "object", "required": [ "data", "eof" ], "properties": { "data": { "type": "string", "format": "byte", "description": "Up to 64 KiB of base64 encoded input bytes. Empty data is allowed when eof is true." }, "eof": { "type": "boolean", "description": "Close stdin after this frame." } }, "additionalProperties": false }, "SandboxTerminalSize": { "type": "object", "required": [ "rows", "cols" ], "properties": { "rows": { "type": "integer", "minimum": 1, "maximum": 4096 }, "cols": { "type": "integer", "minimum": 1, "maximum": 4096 } }, "additionalProperties": false }, "SandboxTerminalSizeReceipt": { "type": "object", "required": [ "rows", "cols", "version" ], "properties": { "rows": { "type": "integer", "minimum": 1, "maximum": 4096 }, "cols": { "type": "integer", "minimum": 1, "maximum": 4096 }, "version": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "ScoreBreakdown": { "type": "object", "properties": { "fit": { "type": "number" }, "time_to_result": { "type": "number" }, "cost_to_complete": { "type": "number" }, "recovery_value": { "type": "number" }, "health": { "type": "number" }, "total": { "type": "number" } } }, "SecretMetadata": { "type": "object", "required": [ "id", "name", "version", "created_at" ], "properties": { "name": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "description": "Stable tenant secret ID shared by its versions." } } }, "SecretWrite": { "type": "object", "required": [ "name", "value" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true, "description": "Nonempty UTF-8 secret with at most 4096 encoded bytes and no NUL characters." } } }, "Settlement": { "type": "object", "properties": { "status": { "type": "string" }, "balance_usd": { "type": "number" }, "correlation_id": { "type": "string" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StageInput": { "type": "object", "properties": { "name": { "type": "string" }, "from_stage": { "type": "string" }, "from_output": { "type": "string" } } }, "StagePayload": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "$ref": "#/components/schemas/WorkloadSource" }, "inputs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/StageInput" } }, "continuity": { "$ref": "#/components/schemas/Continuity" }, "requirements": { "$ref": "#/components/schemas/Requirements", "description": "Nonzero/nonempty stage fields override workload requirements. Omitted/zero fields inherit individually." }, "depends_on": { "type": [ "array", "null" ], "items": { "type": "string" } }, "total_units": { "type": "integer", "minimum": 0 }, "outputs": { "type": [ "object", "null" ], "propertyNames": { "pattern": "^[a-z0-9_][a-z0-9._-]{0,63}$", "not": { "pattern": "^nodus\\." } }, "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/OutputDeclaration" } ] }, "description": "Named output paths or file and database sink declarations. Output names are 1 to 64 lowercase letters, digits, dots, underscores or hyphens that do not begin with a dot, a hyphen or nodus. and other names are refused at submission. Sinks support CSV, JSONL and flat Parquet files. Credentials stay on the control plane. Outputs in one stage must use distinct connection and table targets." } }, "required": [ "id", "source" ] }, "StageRunSummary": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "continuity_mode": { "type": "string" }, "completed_units": { "type": "integer" }, "total_units": { "type": "integer" }, "last_loss": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metric_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metric_step": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latest_manifest": { "anyOf": [ { "$ref": "#/components/schemas/CheckpointSummary" }, { "type": "null" } ] }, "metric_total_steps": { "type": "integer", "description": "Optional reported training display metric. Independent of recovery progress." }, "metric_epoch": { "type": "number", "description": "Optional reported training display metric. Independent of recovery progress." }, "metric_total_epochs": { "type": "number", "description": "Optional reported training display metric. Independent of recovery progress." } } }, "SubmitResult": { "type": "object", "properties": { "id": { "type": "string" }, "workload_id": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" } }, "required": [ "id", "workload_id", "status", "revision" ] }, "UnitMetrics": { "type": "object", "properties": { "units_completed": { "type": "integer", "minimum": 0 }, "p50_ms": { "type": [ "number", "null" ], "minimum": 0 }, "p95_ms": { "type": [ "number", "null" ], "minimum": 0 }, "cost_per_unit_usd": { "type": [ "number", "null" ], "minimum": 0, "description": "Posted workload charges divided by observed unique completed units. Excludes unsettled charges." }, "dropped_observations": { "type": "integer", "minimum": 0, "description": "Runner queue overflow observations. A nonzero value means measurements are incomplete." } } }, "Workload": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "spend_usd": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/WorkloadPayload" }, "route": { "anyOf": [ { "$ref": "#/components/schemas/CustomerRouteSummary" }, { "type": "null" } ] }, "latest_checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/CheckpointSummary" }, { "type": "null" } ] }, "stages": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/StageRunSummary" } }, "meter": { "$ref": "#/components/schemas/Meter" }, "unit_metrics": { "anyOf": [ { "$ref": "#/components/schemas/UnitMetrics" }, { "type": "null" } ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/WorkloadLink" }, "description": "Run links captured from live output, available before completion." }, "sink_error": { "type": "string", "description": "Value-free database sink failure. Workload completion is independent of sink loading." }, "checkpoint_preparation": { "type": "array", "items": { "$ref": "#/components/schemas/CheckpointPreparationSummary" }, "description": "Detail-only source preparation status for stages requesting managed checkpoint integration. Does not assert runtime framework compatibility or successful application recovery." }, "distributed": { "type": "array", "items": { "$ref": "#/components/schemas/DistributedCustomerGroup" }, "description": "Detail-only distributed status. Select a member_id from this list to read member logs. Omitted for workloads without distributed groups." } } }, "WorkloadEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "payload": { "type": [ "object", "null" ], "additionalProperties": {} }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkloadInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$", "description": "Unique input name. Must not conflict with a stage input name." }, "uri": { "type": "string", "enum": [ "" ], "description": "Retained wire field. Nonempty direct input URIs are rejected. Import data first and supply asset_id." }, "asset_id": { "type": "string", "description": "Identifier of a dataset previously imported into this team. Raw external download URLs must be imported before submission.", "pattern": "^asset_[A-Za-z0-9-]{1,64}$" }, "cache": { "type": "boolean", "default": false, "description": "Opt in to the team digest cache in the selected execution region. The first materializing workload remains the storage billing owner under its existing spending cap. Cache retention uses workspace limits and the configured storage rate." }, "bucket": { "$ref": "#/components/schemas/BucketInput" } }, "required": [ "name" ], "oneOf": [ { "required": [ "asset_id" ], "not": { "required": [ "bucket" ] } }, { "required": [ "bucket" ], "not": { "anyOf": [ { "required": [ "asset_id" ] }, { "required": [ "cache" ] } ] } } ] }, "WorkloadListItem": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "spend_usd": { "type": "number" }, "revision": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "meter": { "$ref": "#/components/schemas/Meter" }, "owner_user_id": { "type": [ "string", "null" ], "description": "Member who submitted the workload. Null for historical or unattributed submissions. Attribution is assigned by the server." }, "name": { "type": "string", "maxLength": 120, "description": "Optional display name for the run, saved across sessions. Control characters are not allowed." }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/WorkloadLink" }, "description": "Run links captured from live output, available before completion." } } }, "WorkloadPayload": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/WorkloadSource" }, "inputs": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WorkloadInput" }, "description": "Up to eight imported dataset assets. Each asset is extracted before the command starts and exposed through its NODUS_INPUT_ directory. Direct input URIs are unsupported.", "maxItems": 8 }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "optimization": { "type": "string", "enum": [ "", "automatic", "lowest_cost", "lower_cost", "balanced", "faster", "fastest" ], "deprecated": true, "description": "Deprecated compatibility field. Optimization tiers are not currently supported. New submissions use automatic routing regardless of accepted legacy values. Nodus uses qualified runtime-cost estimates when comparable measurements cover all eligible configurations. Otherwise it provisionally ranks by hourly price with a temporary preference for compatible configurations without a recent matching startup failure. Resource, availability, spending and independent price limits remain enforced." }, "outcome": { "$ref": "#/components/schemas/Outcome" }, "policy": { "$ref": "#/components/schemas/Policy" }, "continuity": { "$ref": "#/components/schemas/Continuity" }, "framework": { "type": "string", "enum": [ "", "train_eval" ], "description": "train_eval expands prepare/train/eval using your command and NODUS_STAGE_ID. Prefer explicit stages for custom pipelines." }, "stages": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/StagePayload" } }, "name": { "type": "string", "maxLength": 120, "description": "Optional display name for the run, saved across sessions. Control characters are not allowed." }, "rl": { "anyOf": [ { "$ref": "#/components/schemas/RLMetadata" }, { "type": "null" } ], "description": "Optional RL experiment association for a customer-provided command. Omit or set null for an ordinary workload. Unknown fields inside a non-null RL object are rejected. This field does not configure the command or make a catalog environment executable." }, "placement": { "$ref": "#/components/schemas/Placement" }, "connections": { "type": "array", "maxItems": 1, "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,127}$" }, "description": "One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode." }, "sweep_id": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$", "description": "Optional wandb run group. Defaults to the workload ID. This does not create or schedule a sweep." } }, "description": "Customer workload request. Supply source.image/source.command, explicit stages, or the train_eval framework with source.command. Unknown top-level JSON fields are currently ignored for compatibility: use documented names. A non-null rl object follows the stricter RLMetadata contract. The SDK validates its top-level arguments. Numeric fields retain existing server behavior. No stronger validation is implied here." }, "WorkloadSource": { "type": "object", "properties": { "image": { "type": "string", "default": "python:3.11-slim", "description": "Container image. Include your code and dependencies. Local files are not uploaded automatically." }, "command": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Explicit argv is recommended. Use sh -c explicitly for shell syntax. An omitted command is accepted for compatibility. Do not rely on image ENTRYPOINT execution across deployments." }, "asset_id": { "type": "string", "description": "Identifier of code previously imported into this team. The runner stages it before starting the command.", "pattern": "^(asset_[A-Za-z0-9-]{1,64})?$" } } }, "ResearchWorkspaceConfiguration": { "type": "object", "additionalProperties": false, "required": [ "name", "environment", "gpu", "gpu_count", "gpu_memory_gb" ], "properties": { "kind": {"type": "string", "enum": ["", "workspace", "instance"], "description": "Omission or an empty value preserves a saved workspace. instance creates standalone compute with SSH and local disk only. The kind cannot change after creation. An existing SSH workspace remains a workspace."}, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_.-]+$", "description": "Unique workspace name within the authenticated account. The names . and .. are not accepted." }, "environment": { "type": "string", "enum": ["pytorch-cuda", "pytorch-rocm", "pytorch-cpu", "custom-cuda", "custom-rocm", "custom-cpu"], "description": "Qualified software environment for NVIDIA, AMD or CPU compute. Custom environments require a team-visible runtime_id." }, "runtime_id": {"type": "string", "pattern": "^nodus:runtime:[a-f0-9]{64}$", "description": "Optional immutable image identity from capabilities.runtimes. Selects the workspace Linux distribution and software. Must match environment and remain qualified and visible to the team. Omission preserves the existing managed environment. The selected runtime cannot be changed when editing a saved project."}, "gpu": { "type": "string", "minLength": 0, "maxLength": 64, "description": "GPU model, not a supplier SKU. Use an empty string for CPU instances. Launch requires an exact qualified configuration and eligible capacity." }, "gpu_count": { "type": "integer", "enum": [0, 1, 2, 4, 8], "description": "Exact GPU count on one machine. Use zero for CPU instances. These accepted request values do not establish hardware qualification or current availability." }, "gpu_memory_gb": { "type": "number", "minimum": 0, "maximum": 1024, "description": "Minimum required memory per GPU in GB, not the sum across devices. Positive for GPU instances and zero for CPU instances." }, "compute_class": {"type": "string", "enum": ["accelerator", "vm"], "description": "Omission retains GPU execution. vm requests a CPU-only workspace and requires capabilities.cpu_instances, a CPU environment, empty gpu, zero gpu_count and zero gpu_memory_gb."}, "gpu_form_factor": {"type": "string", "enum": ["", "pcie", "sxm", "nvl"], "description": "Optional required GPU form factor. Omission permits any form factor. Requires direct workspace compute and cannot be set for CPU instances. A selected form factor is enforced during quoting and placement."}, "vcpus": {"type": "integer", "minimum": 0, "maximum": 256, "description": "Minimum vCPUs on a GPU machine. Omission or zero keeps its included resources. CPU instances require exactly 2, 4, 8, 16 or 32 vCPUs."}, "host_memory_gb": {"type": "number", "minimum": 0, "maximum": 4096, "description": "Minimum system RAM in GB, separate from GPU memory. Omission or zero keeps included RAM on GPU machines. CPU instances require a positive value. Custom RAM requires direct workspace compute."}, "disk_gb": {"type": "integer", "anyOf": [{"const": 0}, {"minimum": 80, "maximum": 2048}], "description": "Runtime storage in decimal GB. Omission or zero preserves the existing 80 GB floor. Explicit sizes from 80 through 2048 are accepted. This is separate from the saved project capacity in size_gb. Restoring saved files can require additional allocation."}, "size_gb": { "type": "number", "minimum": 0, "maximum": 10, "description": "Instances require zero and have no saved project storage. For workspaces, omit to use the deployment capacity, or send a positive capacity within capabilities.storage_limit_bytes. With storage_policy_version included-10gb-v1 or r2-standard-10gb-account-v1, send exactly 10 for the 10,000,000,000-byte per-workspace capacity. The account policy shares its free allowance across workspaces. Other deployments use GiB and their displayed capacity limit." }, "ssh_authorized_key": { "type": "string", "maxLength": 8192, "description": "Plain SSH public keys, one per line, up to 20. Private keys, certificates and authorized_keys options are rejected. Machines also admit every SSH key saved by a team member. Instances and SSH-only workspaces on direct compute may omit this field. SSH is then unavailable until a key exists, and a running machine admits newly saved team keys within seconds. Deployments without direct compute still require it and return 400 invalid_ssh_authorized_key when it is missing." } }, "allOf": [{ "if": {"required": ["kind"], "properties": {"kind": {"const": "instance"}}}, "then": { "properties": {"size_gb": {"const": 0}} }, "else": {"properties": {"size_gb": {"minimum": 9.5367431640625e-07}}} }], "if": {"required": ["compute_class"], "properties": {"compute_class": {"const": "vm"}}}, "then": { "required": ["vcpus", "host_memory_gb"], "properties": { "environment": {"enum": ["pytorch-cpu", "custom-cpu"]}, "gpu": {"const": ""}, "gpu_count": {"const": 0}, "gpu_memory_gb": {"const": 0}, "gpu_form_factor": {"const": ""}, "vcpus": {"enum": [2, 4, 8, 16, 32]}, "host_memory_gb": {"exclusiveMinimum": 0} } }, "else": { "properties": { "gpu": {"minLength": 1}, "gpu_count": {"enum": [1, 2, 4, 8]}, "gpu_memory_gb": {"exclusiveMinimum": 0} } } }, "ResearchWorkspaceCapabilities": { "type": "object", "required": [ "available", "storage_limit_bytes", "environments", "gpu_counts", "editors", "browser_available", "workload_submission", "workload_source_limit_bytes" ], "properties": { "standalone_instances": {"type": "boolean", "description": "Qualified direct compute is available for SSH-only standalone instances. Availability and account funding are rechecked at launch."}, "runtimes": { "type": "array", "description": "Qualified workspace images visible to the authenticated team. These select container userspace, not the host kernel. Registry references and other teams' custom images are not exposed.", "items": { "type": "object", "required": ["id", "name", "os", "os_name", "environment", "custom"], "properties": { "id": {"type": "string", "pattern": "^nodus:runtime:[a-f0-9]{64}$"}, "name": {"type": "string"}, "os": {"type": "string", "enum": ["ubuntu-22.04", "ubuntu-24.04", "debian-12", "debian-13"]}, "os_name": {"type": "string"}, "environment": {"type": "string", "enum": ["pytorch-cuda", "pytorch-rocm", "pytorch-cpu", "custom-cuda", "custom-rocm", "custom-cpu"]}, "custom": {"type": "boolean"} } } }, "available": { "type": "boolean", "description": "Whether workspace configuration and browser access are enabled on this deployment. Not a guarantee of qualified hardware, live capacity or successful admission." }, "storage_limit_bytes": { "type": "integer", "format": "int64", "maximum": 10000000000, "description": "Configured project capacity limit in bytes." }, "storage_policy_version": { "type": "string", "description": "The value r2-standard-10gb-account-v1 shares a free decimal 10 GB allowance across the account, with storage-only overage at the server-reported rate. The older included-10gb-v1 policy retains its per-workspace allowance. Both retain a 10 GB per-workspace operational limit. Empty or absent retains existing storage behavior." }, "environments": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description" ], "properties": { "id": { "type": "string", "enum": [ "pytorch-cuda", "pytorch-rocm", "pytorch-cpu" ] }, "name": { "type": "string" }, "description": { "type": "string" } } } }, "gpu_counts": { "type": "array", "items": { "type": "integer", "enum": [ 1, 2, 4, 8 ] }, "description": "Accepted single-machine request counts. This is not a per-model qualification or availability inventory." }, "cpu_instances": {"type": "boolean", "description": "A qualified CPU image and direct CPU lifecycle are enabled. Availability is checked for each requested vCPU count."}, "host_resource_configuration": {"type": "boolean", "description": "Direct workspace compute can enforce custom vCPU and system RAM requirements."}, "qualified_gpu_configurations": { "type": "array", "description": "Canonical GPU model and count pairs qualified for the deployment's exact active image and runtime artifacts. An empty array means no configuration is currently qualified. This is not live capacity or a price quote. Older servers may omit this field. Existing saved configurations remain readable even when absent from this list.", "items": { "type": "object", "required": ["gpu", "gpu_count"], "properties": { "gpu": {"type": "string", "description": "Qualified canonical GPU model."}, "gpu_count": {"type": "integer", "enum": [1, 2, 4, 8]} }, "additionalProperties": false } }, "editors": { "type": "array", "items": { "type": "string", "enum": [ "vscode", "jupyter", "ssh" ] }, "description": "Supported development tool choices for a new workspace." }, "browser_available": { "type": "boolean", "description": "Whether browser connection infrastructure is currently available. Individual connections still require current session and tool readiness." }, "workload_submission": { "type": "boolean", "description": "Whether this deployment supports submitting an independent workload from a saved or running workspace." }, "workload_source_limit_bytes": { "type": "integer", "format": "int64", "description": "Maximum saved-project payload bytes supported by workspace source preparation. The full-capacity path supports 10,000,000,000 bytes with separate bounded archive metadata. Ordinary asset import limits are unchanged." }, "account_funded_sessions": {"type": "boolean", "description": "Whether sessions use account funding without a per-session spending cap. Account credit and spending controls apply, and a session runs until it is stopped. Older servers may omit this capability, which clients must treat as false."}, "deletion_available": {"type": "boolean", "description": "Whether stopped workspace and instance deletion is supported. Clients treat an omitted capability as false. Deletion can be available while new compute launches are disabled."} } }, "WorkspaceWorkloadRequest": { "type": "object", "additionalProperties": false, "required": [ "command" ], "properties": { "command": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Command run from the captured project directory through the environment shell. Whitespace-only commands, NUL characters and commands longer than 8192 UTF-8 bytes are rejected." }, "budget_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "gpu": { "type": "string", "maxLength": 64, "description": "Optional GPU model override. Omit or send an empty string to inherit the workspace configuration." }, "gpu_count": { "type": "integer", "enum": [ 0, 1, 2, 4, 8 ], "description": "Exact GPUs on one machine. Omitted or zero inherits the workspace configuration." }, "gpu_memory_gb": { "type": "number", "minimum": 0, "maximum": 1024, "description": "Memory per GPU in GB. Omitted or zero inherits the workspace configuration." } } }, "WorkspaceArchiveSegment": { "type": "object", "additionalProperties": false, "required": ["sha256", "offset", "bytes"], "properties": { "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "offset": {"type": "integer", "format": "int64", "minimum": 0, "multipleOf": 512}, "bytes": {"type": "integer", "format": "int64", "minimum": 512, "maximum": 67108864, "multipleOf": 512} }, "description": "One contiguous segment of the canonical archive. Offsets begin at zero with no gaps or overlap, and lengths sum to archive_bytes." }, "WorkspaceArchiveInventory": { "type": "object", "additionalProperties": false, "required": ["sha256", "payload_bytes", "entries"], "properties": { "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Versioned inventory digest derived from ordered paths, file bytes and metadata. The server verifies it against the uploaded archive."}, "payload_bytes": {"type": "integer", "format": "int64", "minimum": 0, "maximum": 10000000000}, "entries": {"type": "integer", "minimum": 1, "maximum": 100000} } }, "WorkspaceArchiveManifest": { "type": "object", "additionalProperties": false, "required": ["version", "archive_sha256", "archive_bytes", "inventory", "segments"], "properties": { "version": {"type": "integer", "const": 3}, "archive_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "archive_bytes": {"type": "integer", "format": "int64", "minimum": 1024, "maximum": 10536870912, "multipleOf": 512}, "inventory": {"$ref": "#/components/schemas/WorkspaceArchiveInventory"}, "segments": {"type": "array", "minItems": 1, "maxItems": 100160, "items": {"$ref": "#/components/schemas/WorkspaceArchiveSegment"}} }, "description": "Version 3 canonical workspace archive commitment, limited to 16 MiB of manifest JSON. Requires a qualified archive writer. Arbitrary tar, zip or compressed bytes are not accepted. The archive permits ordered regular files, directories and confined symbolic links, with at most 10 GB of payload and 512 MiB of archive metadata. Verification checks the complete archive and inventory before replacing saved files." }, "WorkspaceTransferRequest": { "type": "object", "additionalProperties": false, "required": ["idempotency_key", "manifest"], "properties": { "idempotency_key": {"type": "string", "minLength": 1, "maxLength": 128, "description": "Caller-retained key without leading or trailing whitespace. Retain the same manifest and replacement revision when retrying."}, "manifest": {"$ref": "#/components/schemas/WorkspaceArchiveManifest"}, "replace_revision": {"type": "integer", "format": "int64", "minimum": 0, "description": "Observed storage_revision required to replace previously saved files. A changed revision conflicts instead of overwriting newer files."} } }, "WorkspacePricePreview": { "type": "object", "required": ["public_price_available", "currency", "gpu_count", "observed_at", "expires_at", "estimate_only"], "properties": { "hourly_usd": {"type": "number", "exclusiveMinimum": 0, "description": "Public price-sheet reference in USD per hour for the entire machine. Omitted when that configuration has no published rate. This is not the final compute charge. Do not multiply by gpu_count."}, "public_price_available": {"type": "boolean", "description": "Whether the public sheet lists an hourly rate for this configuration. A missing public rate does not block starting available compute."}, "currency": {"type": "string", "const": "USD"}, "gpu_count": {"type": "integer", "enum": [0, 1, 2, 4, 8]}, "observed_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time", "description": "Refresh the estimate after this timestamp."}, "estimate_only": {"type": "boolean", "const": true} }, "description": "Read-only availability check with the public price-sheet reference when listed. Does not allocate compute, reserve capacity or lock a price. Actual compute expenditure is published as one final aggregate charge after the session." }, "WorkspaceTransfer": { "type": "object", "required": ["id", "workspace_id", "state", "base_revision", "manifest_sha256", "manifest_bytes", "uploaded_segments"], "properties": { "id": {"type": "string", "format": "uuid"}, "workspace_id": {"type": "string"}, "failure_code": {"type": "string", "description": "Recorded verification failure when present. Inspect state before retrying or beginning a replacement transfer."}, "state": {"type": "string", "enum": ["uploading", "queued", "verifying", "committed", "abandoned"]}, "base_revision": {"type": "integer", "format": "int64", "minimum": 0}, "manifest_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "manifest_bytes": {"type": "integer", "format": "int64", "minimum": 1, "maximum": 16777216}, "uploaded_segments": {"type": "array", "items": {"type": "integer", "minimum": 0}, "description": "Zero-based indexes already verified for this transfer. Empty when no segment is present."} } }, "WorkspaceWorkload": { "type": "object", "required": ["id", "status", "created_at", "source_revision"], "properties": { "id": {"type": "string"}, "status": {"type": "string"}, "created_at": {"type": "string", "format": "date-time"}, "source_revision": {"type": "string", "description": "Digest identifying the immutable saved project revision used for this workload."} } }, "WorkspaceSourceStorage": { "type": "object", "required": [ "included_bytes", "retained_bytes", "reserved_bytes", "available_bytes", "billing_enabled" ], "properties": { "included_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Included source retention limit. Currently 21,073,741,824 bytes, sufficient for two maximum workspace archives including bounded metadata." }, "retained_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "reserved_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "available_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "billing_enabled": { "type": "boolean", "const": false }, "cleanup_pending_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Bytes awaiting confirmed cleanup of uncertain source writes. Already included in reserved_bytes, not additional quota usage. A local observation timeout does not release them." } }, "description": "Included account storage for generated workload source copies. This pool is separate from billed saved-workspace storage and ordinary asset import limits. Identical captured revisions reuse a physical copy. Reserved bytes can remain until pending writes or deletion are settled." }, "WorkspaceSourceAlias": { "type": "object", "required": [ "source_id", "workspace_id", "source_revision", "exporter_version", "state", "removable", "shared_alias_count" ], "properties": { "source_id": { "type": "string" }, "workspace_id": { "type": "string" }, "source_revision": { "type": "string" }, "exporter_version": { "type": "string" }, "state": { "type": "string" }, "removable": { "type": "boolean", "description": "Whether this alias can currently be removed. Active workloads protect their source." }, "shared_alias_count": { "type": "integer", "minimum": 1, "description": "References sharing this physical source copy. Deleting one alias need not release bytes." } } }, "WorkspacePendingSubmission": { "type": "object", "required": [ "id", "workspace_id", "idempotency_key", "request", "state", "created_at" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "request": { "$ref": "#/components/schemas/WorkspaceWorkloadRequest" }, "state": { "type": "string", "enum": [ "saving", "exporting", "cleanup_pending", "ready", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "deadline_at": { "type": "string", "format": "date-time" }, "error": { "type": "string" } }, "description": "An authenticated recoverable submission. Resume only after an explicit customer action by sending this exact request and idempotency key to the same workspace. Reading this record does not admit a workload. Commands can contain sensitive values and must not be persisted in browser storage or analytics. cleanup_pending means the saved project is safe while a queued source waits for storage cleanup. Resume with the same request and key after cleanup. This state does not confirm workload admission." }, "WorkspaceWorkloadList": { "type": "object", "required": [ "workloads" ], "properties": { "workloads": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/WorkspaceWorkload" } }, "pending_submissions": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspacePendingSubmission" } }, "source_storage": { "$ref": "#/components/schemas/WorkspaceSourceStorage" } } }, "ResearchWorkspaceMeter": { "type": "object", "description": "Lifetime charges for the current compute session, including platform fees and excluding retained workspace storage. Settled and unposted accrued amounts are consistent as of the same time. Values are for the whole machine and must not be multiplied by gpu_count.", "required": ["settled_usd", "accruing_usd", "accruing_rate_usd_hour", "total_now_usd", "as_of", "compute_settled_usd", "platform_fee_settled_usd", "subscription_settled_usd", "compute_accruing_usd", "platform_fee_accruing_usd"], "properties": { "settled_usd": {"type": "number", "description": "Posted compute and platform charges across this session's entire lifetime, including prior billing months."}, "accruing_usd": {"type": "number", "description": "Unposted compute and platform charges through as_of."}, "accruing_rate_usd_hour": {"type": "number", "description": "Current whole-node hourly charge rate. Zero when no charge is growing."}, "total_now_usd": {"type": "number", "description": "settled_usd plus accruing_usd at as_of."}, "as_of": {"type": "string", "format": "date-time"}, "compute_settled_usd": {"type": "number"}, "platform_fee_settled_usd": {"type": "number"}, "subscription_settled_usd": {"type": "number", "description": "Zero for workspace compute sessions."}, "storage_settled_usd": {"type": "number", "default": 0, "description": "Zero for workspace compute sessions. Saved-file charges belong to the account meter."}, "model_settled_usd": {"type": "number", "default": 0, "description": "Zero for workspace compute sessions. Managed model charges belong to the account meter."}, "shared_settled_usd": {"type": "number", "default": 0, "description": "Zero for workspace compute sessions. Shared service charges belong to the account meter."}, "compute_accruing_usd": {"type": "number"}, "platform_fee_accruing_usd": {"type": "number"}, "final_charge_usd": {"type": "number", "minimum": 0, "description": "Immutable aggregate lifetime compute charge once the session has stopped and all required compute cost records are complete. Excludes saved-file storage, which can continue to incur separate usage charges. Omitted while finalizing."}, "charge_state": {"type": "string", "enum": ["estimated", "final"], "description": "Present for metered compute sessions. Stopped sessions remain estimated while required cost records are unavailable. Historical contracts omit this field."} } }, "ResearchWorkspaceAccountStorage": { "type": "object", "required": [ "policy_version", "included_bytes", "retained_bytes", "billable_bytes", "rate_usd_gb_month", "charged_usd", "status", "as_of" ], "properties": { "policy_version": { "type": "string", "description": "Version of the account's saved-file storage policy." }, "included_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Current shared free allowance across eligible saved files. An active storage promotion may provide an allowance." }, "retained_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Verified saved-file payload covered by the current policy. Earlier research storage is reported separately in legacy_retained_bytes." }, "legacy_retained_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Saved research payload retaining earlier pricing, excluded from the current policy allowance." }, "legacy_charged_usd": { "type": "number", "minimum": 0, "description": "Lifetime posted research storage charges under the earlier policy." }, "billable_bytes": { "type": "integer", "format": "int64", "minimum": 0, "description": "Saved payload above the account allowance." }, "rate_usd_gb_month": { "type": "number", "minimum": 0, "description": "Server-reported fixed USD rate per decimal GB-month when applicable. For measured-cost pricing, use pricing_basis and posted charges. A zero rate does not indicate free storage." }, "pricing_basis": { "type": "string", "description": "Billing basis for storage charges when the policy does not use a fixed monthly rate." }, "charged_usd": { "type": "number", "minimum": 0, "description": "Lifetime posted storage charges under the current policy, separate from compute and legacy_charged_usd." }, "status": { "type": "string", "enum": [ "inactive", "included", "funded", "funding_required" ] }, "as_of": { "type": "string", "format": "date-time" } }, "description": "Account-wide saved-file usage and posted charges. The current measured-cost policy reports its pricing basis and posted charges. Earlier fixed-rate policies report their applicable monthly rate separately. Use server-reported charges instead of deriving a bill from the current byte count. File export and deletion remain available with stopped compute." }, "ResearchWorkspaceFileRevision": { "type": "object", "additionalProperties": false, "required": [ "storage_revision" ], "properties": { "storage_revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "Observed saved-file revision, required to guard the selected export or deletion." } } }, "ResearchWorkspaceExportSegment": { "type": "object", "required": [ "index", "sha256", "offset", "bytes", "url", "download_path" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "offset": { "type": "integer", "format": "int64", "minimum": 0 }, "bytes": { "type": "integer", "format": "int64", "minimum": 512, "maximum": 67108864 }, "url": { "type": "string", "format": "uri", "description": "Short-lived signed HTTPS object URL. Do not forward Nodus authentication or cookies to this URL." }, "download_path": { "type": "string", "description": "Authenticated API-relative path for downloading this segment without cross-origin browser requests." } } }, "ResearchWorkspaceFileExport": { "type": "object", "required": [ "id", "workspace_id", "storage_revision", "format", "expires_at", "urls_expire_at", "manifest", "segments" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string" }, "storage_revision": { "type": "integer", "format": "int64", "minimum": 0 }, "format": { "type": "string", "const": "research-archive-v3" }, "expires_at": { "type": "string", "format": "date-time", "description": "Fixed expiry of the retained export revision, 24 hours after admission." }, "urls_expire_at": { "type": "string", "format": "date-time", "description": "Earliest signed URL expiry on this page, at most 15 minutes. Read the page again for fresh URLs." }, "manifest": { "$ref": "#/components/schemas/WorkspaceArchiveManifest" }, "segments": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/ResearchWorkspaceExportSegment" } }, "next_offset": { "type": "integer", "minimum": 0, "description": "Read the next page at this offset. Omitted on the final page." } } }, "ResearchWorkspaceFileDeletion": { "type": "object", "required": [ "workspace_id", "storage_revision", "deleted" ], "properties": { "workspace_id": { "type": "string" }, "storage_revision": { "type": "integer", "format": "int64", "minimum": 0 }, "deleted": { "type": "boolean", "const": true } } }, "ResearchWorkspaceStorage": { "type": "object", "required": ["rate_usd_gib_month", "price_version", "retained_bytes", "charged_usd", "as_of"], "properties": { "rate_usd_gib_month": {"type": "number", "description": "Approved retained-storage rate in USD per GiB-month, separate from compute. Zero when storage billing is disabled."}, "price_version": {"type": "string", "description": "Approved storage price version, or an empty string when billing is disabled."}, "retained_bytes": {"type": "integer", "format": "int64", "description": "Total retained storage for this workspace, including data needed to restore saved files. May exceed the latest save's stored_bytes."}, "charged_usd": {"type": "number", "description": "Lifetime posted storage charges for this workspace, not a compute-session charge."}, "as_of": {"type": "string", "format": "date-time"} } }, "WorkspacePendingUpload": { "type": "object", "description": "An unfinished customer folder upload. Use its ID with the existing transfer status, segment, finalize and discard routes. Available from any authenticated browser for this account. Reselecting files requires the same manifest commitment. Runtime saves are excluded.", "required": ["id", "workspace_id", "state", "base_revision", "manifest_sha256", "manifest_bytes"], "properties": { "id": {"type": "string", "format": "uuid"}, "workspace_id": {"type": "string"}, "state": {"type": "string", "enum": ["uploading", "queued", "verifying"]}, "base_revision": {"type": "integer", "minimum": 0}, "manifest_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "manifest_bytes": {"type": "integer", "minimum": 1, "maximum": 16777216} } }, "ResearchWorkspace": { "description": "A durable named project and its saved configuration, with a replaceable compute session. Only saved files under /workspace are restored, not process memory.", "allOf": [ {"$ref": "#/components/schemas/WorkspaceRecord"}, { "type": "object", "required": ["holder_id", "saved_at", "stored_bytes", "last_error", "saving_for_termination", "configuration", "configuration_revision", "pending_upload", "storage_revision", "storage_policy_version", "session", "meter", "state", "status_message", "connections", "storage"], "properties": { "configuration": {"$ref": "#/components/schemas/ResearchWorkspaceConfiguration"}, "pending_upload": {"oneOf": [{"$ref": "#/components/schemas/WorkspacePendingUpload"}, {"type": "null"}]}, "configuration_revision": {"type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Saved configuration identity. Send this observed value when editing settings. Independent from the saved-file revision."}, "storage_revision": {"type": "integer", "format": "int64", "minimum": 0, "description": "Current saved-file revision used to guard a stopped-workspace replacement."}, "storage_policy_version": {"type": "string", "description": "Storage policy recorded for this workspace. Transfer endpoints require a compatible versioned storage policy on the workspace and deployment."}, "session": { "oneOf": [{"$ref": "#/components/schemas/Sandbox"}, {"type": "null"}], "description": "Current associated compute session, or null before one is available. Use session.id in the stop request." }, "meter": { "oneOf": [{"$ref": "#/components/schemas/ResearchWorkspaceMeter"}, {"type": "null"}], "description": "Current session's lifetime compute charges, or null without a session." }, "state": { "type": "string", "enum": ["stopped", "creating", "ready", "running", "idle", "suspended", "resuming", "recovering", "stopping", "failed", "freezing", "frozen"], "description": "Workspace lifecycle view. stopping includes a pending final save or unconfirmed compute release. Tool access also requires its connections flag." }, "status_message": {"type": "string"}, "connections": { "type": "object", "required": ["editor", "notebook", "ssh"], "properties": { "editor": {"type": "boolean"}, "notebook": {"type": "boolean"}, "ssh": {"type": "boolean"} }, "description": "Current tool readiness for the authorized compute session. Compute may continue to accrue charges while these flags are false." }, "storage": {"$ref": "#/components/schemas/ResearchWorkspaceStorage"} } } ] }, "ResearchWorkspaceList": { "type": "object", "required": ["workspaces"], "properties": { "workspaces": { "type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/ResearchWorkspace"} }, "next_cursor": { "type": "string", "maxLength": 1024, "description": "Opaque continuation for this account and list. Empty when this page has no further records." } } }, "ResearchWorkspaceStopRequest": { "type": "object", "additionalProperties": false, "required": ["session_id"], "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Original session.id to stop, owned by this account and workspace. Retain this exact value with the Idempotency-Key when retrying. A retry never selects a newer replacement session." } } }, "ResearchWorkspaceConnectionRequest": { "type": "object", "additionalProperties": false, "required": ["tool"], "properties": { "tool": {"type": "string", "enum": ["editor", "notebook", "ssh"]} } }, "ResearchWorkspaceBrowserConnection": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS tool URL containing a one-time grant in its fragment. Open within one minute. Redemption creates a host-only secure browser session lasting at most one hour, subject to ongoing authorization. Treat this URL as a secret. Request another connection if it expires or has already been used." } } }, "ResearchWorkspaceConnectionRetryRequest": { "type": "object", "additionalProperties": true, "required": ["tool"], "description": "Select one browser tool. Unknown fields are ignored. The complete JSON body must not exceed 512 bytes.", "properties": { "tool": {"type": "string", "enum": ["editor", "notebook"]} } }, "ResearchWorkspaceConnectionRetry": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": {"type": "string", "const": "retry_scheduled"} } }, "ResearchWorkspaceSSHConnection": { "type": "object", "required": ["host", "alias", "user", "command", "ssh_config", "gateway_fingerprint", "gateway_known_hosts"], "properties": { "host": {"type": "string", "description": "SSH configuration alias to open in a local SSH client or VS Code Remote SSH."}, "alias": {"type": "string", "description": "Same as host. Derived from the workspace name, or nodus- followed by the workspace id."}, "user": {"type": "string", "const": "nodus"}, "command": {"type": "string", "description": "One-line ssh command that works without the configuration block. It names the workspace and contains no credential."}, "ssh_config": {"type": "string", "description": "OpenSSH configuration using the workspace gateway as ProxyJump. Requires the private key corresponding to the saved public key. Do not disable host-key checking."}, "gateway_fingerprint": {"type": "string", "description": "SHA256 fingerprint of the deployment's stable SSH gateway host key."}, "gateway_known_hosts": {"type": "string", "description": "OpenSSH known_hosts entry for the gateway, to install before connecting. The guest has a separate project-persisted host key and first-use confirmation."} } }, "WorkspaceWebSocketSSHConnection": { "type": "object", "required": ["host", "alias", "user", "command", "requires", "ssh_config", "transport", "workspace_id", "session_id", "generation"], "properties": { "host": {"type": "string", "description": "OpenSSH configuration alias to open from a terminal or VS Code Remote SSH."}, "alias": {"type": "string", "description": "Same as host. Derived from the workspace name, or nodus- followed by the workspace id."}, "user": {"type": "string", "const": "nodus"}, "command": {"type": "string", "description": "One-line ssh command using nodus workspaces ssh-proxy. It names the workspace and contains no credential."}, "requires": {"type": "string", "const": "nodus-cli", "description": "Local tool the command runs."}, "ssh_config": {"type": "string", "description": "OpenSSH configuration using nodus workspaces ssh-proxy as ProxyCommand. The command reads the existing Nodus sign-in and contains no credential. The matching SSH private key is still required. Confirm the project host key on first use."}, "transport": {"type": "string", "const": "websocket"}, "workspace_id": {"type": "string"}, "session_id": {"type": "string"}, "generation": {"type": "integer", "minimum": 1} } }, "WorkspaceCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "size_gb" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "size_gb": { "type": "number", "exclusiveMinimum": 0, "description": "Requested capacity in GiB within the configured team limit." } } }, "WorkspaceRecord": { "type": "object", "required": [ "id", "name", "size_gb", "billing_status" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size_gb": { "type": "number" }, "holder_id": { "type": [ "string", "null" ] }, "saved_at": { "type": [ "string", "null" ], "format": "date-time" }, "expired_at": { "type": ["string", "null"], "format": "date-time", "default": null, "description": "Time the tenant retention policy expired saved workspace state. The namespace remains listed." }, "cleanup_pending": { "type": "boolean", "default": false, "description": "Expired workspace objects still require cleanup. An empty namespace can be reused after cleanup settles." }, "stored_bytes": { "type": [ "integer", "null" ] }, "last_error": { "type": "string" }, "saving_for_termination": { "type": "boolean" }, "billing_status": { "type": "string", "enum": [ "disabled_no_approved_storage_rate", "metered_subject_to_account_limits", "included_workspace_storage", "account_workspace_storage", "ephemeral_instance" ], "description": "Storage billing policy for this record. ephemeral_instance has no saved storage or storage charge. Its compute session is billed separately." } } }, "WorkspaceSelection": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_.-]+$" }, "mount": { "type": "string", "default": "/workspace", "description": "Dedicated top-level directory. System directories cannot be used." } } }, "Pool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "state": { "type": "string" }, "wait_policy": { "type": "string", "enum": [ "never", "after_wait", "cheaper" ], "description": "never keeps waiting for private capacity without market fallback. after_wait permits fallback after the retained wait. cheaper requires active Predict and a current forecast showing lower expected market completion cost. Missing evidence keeps waiting." }, "burst_approval": { "type": "string", "enum": [ "auto", "above_threshold", "always" ] }, "burst_timeout_behaviour": { "type": "string", "enum": [ "keep_waiting", "cancel" ] }, "predict_enabled": { "type": "boolean" }, "route_enabled": { "type": "boolean" }, "sandbox_capable": { "type": "boolean" }, "wait_alpha": { "type": "number", "minimum": 0, "description": "Finite nonnegative wait tolerance multiplier. New pools default to 0.1." }, "waiting_budget_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "burst_threshold_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807, "description": "Approval threshold in USD micros." }, "platform_rate_micros": { "type": "integer", "format": "int64", "minimum": 0, "description": "Accepted Route rate per active customer device-hour in USD micros. Retained when Route is disabled." }, "owned_cost_micros_per_hour": { "type": "integer", "format": "int64", "minimum": 0, "description": "Customer-supplied owned hardware cost in USD micros per hour. This value does not create a charge." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "route_price_version": { "type": "string", "description": "Accepted Nodus Route pricing version. byoc-free-v1 with a zero platform rate identifies free cloud-connected execution. Absent before pricing terms are accepted. Retained when routing is disabled." } }, "required": [ "id", "name", "kind", "state", "wait_policy", "burst_approval", "burst_timeout_behaviour", "predict_enabled", "route_enabled", "sandbox_capable", "wait_alpha", "waiting_budget_pct", "burst_threshold_micros", "platform_rate_micros", "owned_cost_micros_per_hour", "created_at", "updated_at" ], "description": "Customer infrastructure pool with read-only measurement. Cloud-connected pools have free Predict and Route under byoc-free-v1. Other pools retain their separately accepted pricing. Each execution host requires host-bound reenrollment. Owned cost is advisory and does not create a charge." }, "PoolCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed nonempty pool name, at most 200 UTF-8 bytes." } }, "required": [ "name" ], "additionalProperties": false }, "PoolPatchRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed nonempty pool name, at most 200 UTF-8 bytes." }, "owned_cost_micros_per_hour": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807 }, "predict_enabled": { "type": "boolean" }, "accepted_predict_rate_version": { "type": "string" }, "accepted_predict_monthly_micros": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "route_enabled": { "type": "boolean" }, "accepted_route_rate_version": { "type": "string", "description": "Cloud-connected pools accept byoc-free-v1 at zero. Other customer-owned pools require explicit private-supplier-cost-v2 consent on each enable request." }, "accepted_route_rate_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807, "description": "Zero for customer-owned pools. Non-cloud pools require explicit zero with private-supplier-cost-v2 on each enable request. Existing reservations retain their accepted terms." }, "wait_policy": { "type": "string", "enum": [ "never", "after_wait", "cheaper" ], "description": "never keeps waiting for private capacity without market fallback. after_wait permits fallback after the retained wait. cheaper requires active Predict and a current forecast showing lower expected market completion cost. Missing evidence keeps waiting." }, "wait_alpha": { "type": "number", "minimum": 0, "description": "Finite nonnegative wait tolerance multiplier. New pools default to 0.1." }, "waiting_budget_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "burst_approval": { "type": "string", "enum": [ "auto", "above_threshold", "always" ] }, "burst_threshold_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807, "description": "Approval threshold in USD micros." }, "burst_timeout_behaviour": { "type": "string", "enum": [ "keep_waiting", "cancel" ] } }, "additionalProperties": false, "minProperties": 1, "description": "Change Predict separately from other settings. Customer-owned pools have no fixed Predict fee and accept byoc-free-v1 with accepted_predict_monthly_micros 0. The API also permits omitted consent for these free Predict terms. Historical charges remain readable. Disabling requires only predict_enabled false and stops future refresh. Cached views remain readable. Change Route and its waiting settings separately from Predict, name, and owned cost. Enabling Route requires an active pool. Cloud-connected pools use byoc-free-v1 at zero and may omit consent. Other customer-owned pools require explicit private-supplier-cost-v2 consent at zero fixed platform rate. Cloud provider charges and separately authorized market capacity remain separate. Consent fields are rejected unless enabling. Disabling blocks new admission and retains accepted terms, existing work, and exact cleanup." }, "PoolEnrollmentTokenRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "observe", "execute" ], "default": "observe" }, "host_id": { "type": "string", "description": "Existing host in this pool required for execute reenrollment. Rejected for observe mode." } }, "additionalProperties": false, "description": "Observe is the default, including an omitted body. Execute mode requires an existing host_id and a fresh installation. Token issuance does not activate Route or change host credentials until enrollment." }, "PoolEnrollmentToken": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string", "description": "Secret single-use enrollment token returned only when issued. Keep it out of logs and source control." }, "mode": { "type": "string", "enum": [ "observe", "execute" ] }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "token", "mode", "expires_at" ] }, "PoolInventoryDevice": { "type": "object", "properties": { "device_index": { "type": "integer", "minimum": 0 }, "model": { "type": "string" }, "memory_mb": { "type": "integer", "format": "int64", "minimum": 0 }, "device_uuid": { "type": "string" } }, "required": [ "device_index", "model", "memory_mb", "device_uuid" ] }, "PoolHostInventory": { "type": "object", "properties": { "hostname": { "type": "string" }, "kernel": { "type": "string" }, "container_runtime": { "type": "string" }, "memory_mb": { "type": "integer", "format": "int64", "minimum": 0 }, "disk_mb": { "type": "integer", "format": "int64", "minimum": 0 }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/PoolInventoryDevice" } } }, "required": [ "hostname", "kernel", "memory_mb", "disk_mb", "devices" ] }, "PoolHostDevice": { "type": "object", "properties": { "id": { "type": "string" }, "host_id": { "type": "string" }, "pool_id": { "type": "string" }, "device_index": { "type": "integer", "minimum": 0 }, "model": { "type": "string" }, "memory_mb": { "type": "integer", "format": "int64", "minimum": 0 }, "device_uuid": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "host_id", "pool_id", "device_index", "model", "memory_mb", "device_uuid", "state" ] }, "PoolHost": { "type": "object", "properties": { "id": { "type": "string" }, "pool_id": { "type": "string" }, "name": { "type": "string" }, "agent_version": { "type": "string" }, "agent_mode": { "type": "string" }, "state": { "type": "string", "enum": [ "enrolling", "ready", "draining", "lost", "removed" ] }, "inventory": { "$ref": "#/components/schemas/PoolHostInventory" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/PoolHostDevice" } }, "last_heartbeat_at": { "type": [ "string", "null" ], "format": "date-time" }, "drain_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrolled_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "pool_id", "name", "agent_version", "agent_mode", "state", "inventory", "devices", "last_heartbeat_at", "drain_requested_at", "enrolled_at" ] }, "PoolList": { "type": "object", "properties": { "pools": { "type": "array", "items": { "$ref": "#/components/schemas/Pool" } } }, "required": [ "pools" ] }, "PoolHostList": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/PoolHost" } } }, "required": [ "hosts" ] }, "PoolUtilizationMetrics": { "type": "object", "properties": { "capacity_seconds": { "type": "integer", "minimum": 0 }, "unknown_seconds": { "type": "integer", "minimum": 0 }, "allocated_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "busy_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "idle_allocated_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "stranded_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "foreign_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "fragmentation_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Workload-seconds when a multi-device request waited because free devices were split across hosts." }, "queued_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Workload-seconds waiting for the pool. Null when retained queue history cannot cover the window." }, "burst_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Settled customer-active burst device-seconds clipped to the requested window." }, "allocation_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "busy_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "busy_of_allocated_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "data_status": { "type": "string", "enum": [ "complete", "partial", "no_data" ] }, "burst_cost_micros": { "type": [ "integer", "null" ], "minimum": 0, "description": "Exact settled customer cost in USD micros for burst executions wholly inside the requested window. Null when unsettled or crossing the window boundary." } }, "required": [ "capacity_seconds", "unknown_seconds", "allocated_seconds", "busy_seconds", "idle_allocated_seconds", "stranded_seconds", "foreign_seconds", "fragmentation_seconds", "queued_seconds", "burst_seconds", "allocation_pct", "busy_pct", "busy_of_allocated_pct", "data_status", "burst_cost_micros" ], "description": "Totals cover retained ready-device hourly rows only. Complete means all represented ready seconds have activity evidence, not that the pool existed throughout the requested range. Partial means some ready seconds lack observations and all activity totals and percentages are null. No data means no retained rows. Zero capacity has null percentages. Missing activity is never counted as idle or stranded. Fragmentation, queued and burst are unavailable without Route and remain null in the observe ledger. Route measurements use independent durable queue and execution evidence in the pool summary. Host summaries and host buckets keep Route fields null because these cannot be attributed to a private host." }, "PoolUtilizationBucket": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "metrics": { "$ref": "#/components/schemas/PoolUtilizationMetrics" }, "foreign_device_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "start", "end", "metrics", "foreign_device_ids" ], "description": "Half-open UTC bucket. Empty buckets have no_data metrics. Foreign device IDs identify positive observed foreign allocation even when other activity is unknown." }, "PoolUtilizationHost": { "type": "object", "properties": { "host_id": { "type": "string" }, "name": { "type": "string" }, "device_count": { "type": "integer", "minimum": 0 }, "summary": { "$ref": "#/components/schemas/PoolUtilizationMetrics" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/PoolUtilizationBucket" } } }, "required": [ "host_id", "name", "device_count", "summary", "buckets" ] }, "PoolUtilization": { "type": "object", "properties": { "pool_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "bucket": { "type": "string", "enum": [ "hour", "day" ] }, "summary": { "$ref": "#/components/schemas/PoolUtilizationMetrics" }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/PoolUtilizationHost" } } }, "required": [ "pool_id", "from", "to", "bucket", "summary", "hosts" ] }, "PoolPredictSubscription": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled", "paused_credits", "paused_cap", "paused_payment", "consent_required" ] }, "rate_version": { "type": "string" }, "monthly_micros": { "type": "integer", "minimum": 0 }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "paid_current_period": { "type": "boolean" }, "enabled_pool_count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "rate_version", "monthly_micros", "period_start", "period_end", "paid_current_period", "enabled_pool_count" ], "description": "Customer-owned pools report byoc-free-v1 and monthly_micros 0, including while active. Free activation and refresh create no subscription charge. paid_current_period normally remains false. For non-cloud pools it records any retained historical funding for the current month, including credits or an accepted postpaid receivable. It does not assert that a postpaid invoice has been paid. Historical charges retain their original rate version and amount." }, "PoolForecastBand": { "type": "object", "properties": { "hour": { "type": "string", "format": "date-time" }, "p10": { "type": "number", "minimum": 0 }, "p50": { "type": "number", "minimum": 0 }, "p90": { "type": "number", "minimum": 0 }, "queue_device_hours": { "type": "number", "minimum": 0, "description": "Known queued demand added to this hourly band. Omitted for historical forecasts without queue evidence." } }, "required": [ "hour", "p10", "p50", "p90" ] }, "PoolForecast": { "type": "object", "properties": { "model": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "insufficient_history" ] }, "as_of": { "type": "string", "format": "date-time" }, "horizon_days": { "type": "integer", "enum": [ 7, 30 ] }, "history_from": { "type": "string", "format": "date-time" }, "history_hours": { "type": "integer", "minimum": 0 }, "required_history_hours": { "type": "integer", "minimum": 0 }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/PoolForecastBand" } }, "queue": { "$ref": "#/components/schemas/PoolForecastQueue" } }, "required": [ "model", "status", "as_of", "horizon_days", "history_from", "history_hours", "required_history_hours", "points" ], "description": "Allocated device-hour demand including foreign allocations. A seasonal baseline requires 672 complete hourly observations. Unknown demand is not replaced with zero. No learned model is claimed unless its registry promotion was verified." }, "PoolForecastEvaluation": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "no_data", "partial", "complete" ] }, "expected_hours": { "type": "integer", "minimum": 0 }, "forecast_hours": { "type": "integer", "minimum": 0 }, "evaluated_hours": { "type": "integer", "minimum": 0 }, "covered_hours": { "type": "integer", "minimum": 0 }, "hourly_coverage": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "pinball_p10": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "pinball_p50": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "pinball_p90": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "complete_days": { "type": "integer", "minimum": 0 }, "covered_days": { "type": "integer", "minimum": 0 }, "daily_coverage": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "from", "to", "status", "expected_hours", "forecast_hours", "evaluated_hours", "covered_hours", "hourly_coverage", "pinball_p10", "pinball_p50", "pinball_p90", "complete_days", "covered_days", "daily_coverage" ], "description": "Last 30 completed UTC days scored only against forecasts issued before the target hour. Missing actuals are excluded and denominators are explicit. Daily coverage is the fraction of complete days with every hour covered, not a nominal 80 percent daily interval." }, "PoolAdvisoryPrice": { "type": "object", "properties": { "rate_micros_per_device_hour": { "type": "integer", "minimum": 0 }, "observed_at": { "type": "string", "format": "date-time" }, "basis": { "type": "string" } }, "required": [ "rate_micros_per_device_hour", "observed_at", "basis" ], "description": "Fresh compatible available market configuration observed with the customer markup. Device-fit hourly advisory only, not a workload completion quote or an executable reservation." }, "PoolForecastSnapshot": { "type": "object", "properties": { "pool_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "forecast": { "$ref": "#/components/schemas/PoolForecast" }, "calibration": { "$ref": "#/components/schemas/PoolForecastEvaluation" }, "owned_devices": { "type": "integer", "minimum": 0 }, "advisory_burst_price": { "anyOf": [ { "$ref": "#/components/schemas/PoolAdvisoryPrice" }, { "type": "null" } ] } }, "required": [ "pool_id", "generated_at", "forecast", "calibration", "owned_devices", "advisory_burst_price" ] }, "PoolRecommendationOutcome": { "type": "object", "properties": { "recorded_at": { "type": "string", "format": "date-time" }, "outcome": { "type": "string" }, "reported_saving_micros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "recorded_at", "outcome", "reported_saving_micros" ], "description": "Immutable customer-reported manual outcome. reported_saving_micros is optional customer testimony, not measured or verified savings. No action is executed by recording an outcome." }, "PoolRecommendationDone": { "type": "object", "properties": { "outcome": { "type": "string", "minLength": 1, "maxLength": 2000 }, "reported_saving_micros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "outcome" ], "additionalProperties": false }, "PoolRecommendation": { "type": "object", "properties": { "id": { "type": "string" }, "pool_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "rightsize", "idle_reclaim", "drain_window", "defragment", "wait_tuning" ] }, "generated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "open", "done", "expired" ] }, "recommendation": { "oneOf": [ { "$ref": "#/components/schemas/PoolRightSizeRecommendation" }, { "$ref": "#/components/schemas/PoolIdleRecommendation" }, { "$ref": "#/components/schemas/PoolDrainRecommendation" }, { "$ref": "#/components/schemas/PoolDefragmentRecommendation" }, { "$ref": "#/components/schemas/PoolWaitTuningRecommendation" } ] }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PoolRecommendationOutcome" }, { "type": "null" } ] } }, "required": [ "id", "pool_id", "kind", "generated_at", "expires_at", "state", "recommendation", "outcome" ] }, "PoolForecastResponse": { "type": "object", "properties": { "pool_id": { "type": "string" }, "predict_enabled": { "type": "boolean" }, "refresh_status": { "type": "string", "enum": [ "active", "disabled", "awaiting_refresh", "stale", "paused_credits", "paused_cap", "paused_payment", "consent_required" ] }, "subscription": { "$ref": "#/components/schemas/PoolPredictSubscription" }, "snapshot": { "anyOf": [ { "$ref": "#/components/schemas/PoolForecastSnapshot" }, { "type": "null" } ] } }, "required": [ "pool_id", "predict_enabled", "refresh_status", "subscription", "snapshot" ] }, "PoolRecommendationsResponse": { "type": "object", "properties": { "pool_id": { "type": "string" }, "predict_enabled": { "type": "boolean" }, "refresh_status": { "type": "string", "enum": [ "active", "disabled", "awaiting_refresh", "stale", "paused_credits", "paused_cap", "paused_payment", "consent_required" ] }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/PoolRecommendation" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque continuation cursor or null when no older records remain. Reuse the same state filter." } }, "required": [ "pool_id", "predict_enabled", "refresh_status", "recommendations", "next_cursor" ], "description": "One page of advice and recorded human outcomes, newest first. Follow next_cursor to read older records. Use state=open for current actionable advice." }, "PoolRightSizeRecommendation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rightsize" ] }, "level": { "type": "string", "enum": [ "recommend" ] }, "risk": { "type": "string", "enum": [ "low", "medium", "high" ] }, "recommended_devices": { "type": "integer", "minimum": 0 }, "expected_savings_micros": { "type": "integer", "minimum": 0 }, "evidence": { "$ref": "#/components/schemas/PoolRightSizeEvidence" } }, "required": [ "kind", "level", "risk", "recommended_devices", "expected_savings_micros", "evidence" ] }, "PoolRightSizeEvidence": { "type": "object", "properties": { "method": { "type": "string" }, "history_from": { "type": "string", "format": "date-time" }, "history_to": { "type": "string", "format": "date-time" }, "history_hours": { "type": "integer", "minimum": 0 }, "horizon_from": { "type": "string", "format": "date-time" }, "horizon_to": { "type": "string", "format": "date-time" }, "horizon_hours": { "type": "integer", "minimum": 0 }, "scenarios_per_hour": { "type": "integer", "minimum": 0 }, "current_devices": { "type": "integer", "minimum": 0 }, "released_devices": { "type": "integer", "minimum": 0 }, "owned_micros_per_device_hour": { "type": "integer", "minimum": 0 }, "burst_micros_per_device_hour": { "type": "integer", "minimum": 0 }, "critical_fractile": { "type": "number", "minimum": 0 }, "expected_burst_device_hours": { "type": "number", "minimum": 0 }, "expected_burst_micros": { "type": "integer", "minimum": 0 }, "released_owned_micros": { "type": "integer", "minimum": 0 }, "advisory_price": { "type": "boolean" }, "demand_distribution": { "type": "array", "items": { "$ref": "#/components/schemas/PoolDemandMass" } } }, "required": [ "method", "history_from", "history_to", "history_hours", "horizon_from", "horizon_to", "horizon_hours", "scenarios_per_hour", "current_devices", "released_devices", "owned_micros_per_device_hour", "burst_micros_per_device_hour", "critical_fractile", "expected_burst_device_hours", "expected_burst_micros", "released_owned_micros", "advisory_price", "demand_distribution" ], "description": "Recomputable prospective scenario costs in USD micros. Uses allocated demand and the observed hourly market price. Expected savings are not measured outcomes or guaranteed cost to completion." }, "PoolDemandMass": { "type": "object", "properties": { "device_hours": { "type": "number", "minimum": 0 }, "scenario_count": { "type": "integer", "minimum": 0 } }, "required": [ "device_hours", "scenario_count" ] }, "PoolIdleRecommendation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idle_reclaim" ] }, "level": { "type": "string", "enum": [ "recommend" ] }, "risk": { "type": "string", "enum": [ "high" ] }, "advisory_only": { "type": "boolean", "const": true }, "host_id": { "type": "string" }, "device_id": { "type": "string" }, "device_index": { "type": "integer", "minimum": 0 }, "expected_savings_micros": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "evidence": { "$ref": "#/components/schemas/PoolIdleEvidence" } }, "required": [ "kind", "level", "risk", "advisory_only", "host_id", "device_id", "device_index", "expected_savings_micros", "expires_at", "evidence" ], "description": "Advisory device allocation with SM below 5 percent for an uninterrupted 30 minutes, supported by one week of observed hourly history. Foreign is only a boolean. No process identity or measured savings are inferred. Evidence expires after three minutes." }, "PoolIdleEvidence": { "type": "object", "properties": { "method": { "type": "string" }, "sm_util_below_pct": { "type": "integer", "minimum": 0 }, "trigger_from": { "type": "string", "format": "date-time" }, "trigger_to": { "type": "string", "format": "date-time" }, "consecutive_seconds": { "type": "integer", "minimum": 0 }, "observed_through": { "type": "string", "format": "date-time" }, "foreign": { "type": "boolean" }, "history_from": { "type": "string", "format": "date-time" }, "history_to": { "type": "string", "format": "date-time" }, "historical_observed_hours": { "type": "integer", "minimum": 0 } }, "required": [ "method", "sm_util_below_pct", "trigger_from", "trigger_to", "consecutive_seconds", "observed_through", "foreign", "history_from", "history_to", "historical_observed_hours" ] }, "PoolDrainRecommendation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "drain_window" ] }, "level": { "type": "string", "enum": [ "recommend" ] }, "risk": { "type": "string", "enum": [ "high" ] }, "advisory_only": { "type": "boolean", "const": true }, "host_id": { "type": "string" }, "expected_savings_micros": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "evidence": { "$ref": "#/components/schemas/PoolDrainEvidence" } }, "required": [ "kind", "level", "risk", "advisory_only", "host_id", "expected_savings_micros", "expires_at", "evidence" ], "description": "A retained UTC drain window with at least three hours remaining at generation. The window may start in the current hour. Expiry is no later than window_to and 24 hours after generation. No measured or estimated saving is invented." }, "PoolDrainEvidence": { "type": "object", "properties": { "method": { "type": "string" }, "window_from": { "type": "string", "format": "date-time" }, "window_to": { "type": "string", "format": "date-time" }, "consecutive_hours": { "type": "integer", "minimum": 0 }, "threshold_devices": { "type": "integer", "minimum": 0 }, "max_p90_device_hours": { "type": "number", "minimum": 0 }, "history_from": { "type": "string", "format": "date-time" }, "history_to": { "type": "string", "format": "date-time" }, "history_hours": { "type": "integer", "minimum": 0 }, "model": { "type": "string" } }, "required": [ "method", "window_from", "window_to", "consecutive_hours", "threshold_devices", "max_p90_device_hours", "history_from", "history_to", "history_hours", "model" ] }, "PoolDefragmentEvidence": { "type": "object", "properties": { "method": { "type": "string" }, "history_from": { "type": "string", "format": "date-time" }, "history_to": { "type": "string", "format": "date-time" }, "observed_hours": { "type": "integer", "minimum": 0 }, "fragmentation_wait_seconds": { "type": "number", "minimum": 0 }, "threshold_seconds": { "type": "number", "minimum": 0 }, "packing_policy": { "type": "string" }, "foreign_jobs_movable": { "type": "boolean", "const": false } }, "required": [ "method", "history_from", "history_to", "observed_hours", "fragmentation_wait_seconds", "threshold_seconds", "packing_policy", "foreign_jobs_movable" ] }, "PoolDefragmentRecommendation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "defragment" ] }, "level": { "type": "string", "enum": [ "recommend" ] }, "risk": { "type": "string", "enum": [ "high" ] }, "advisory_only": { "type": "boolean", "const": true }, "expected_savings_micros": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "evidence": { "$ref": "#/components/schemas/PoolDefragmentEvidence" } }, "required": [ "kind", "level", "risk", "advisory_only", "expected_savings_micros", "expires_at", "evidence" ], "description": "Manual placement advice from 336 fully observed Route hours. No advice is produced from missing placement observations. Foreign jobs are never proposed for movement and savings are not inferred." }, "Placement": { "type": "object", "properties": { "pool": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Customer pool ID. Nonempty, at most 200 UTF-8 bytes, without surrounding whitespace or control characters." }, "prefer": { "type": "string", "enum": [ "any" ], "description": "Skip private pools and use eligible market capacity." } }, "additionalProperties": false, "oneOf": [ { "required": [ "pool" ], "not": { "required": [ "prefer" ] } }, { "required": [ "prefer" ], "not": { "required": [ "pool" ] } } ], "description": "Choose exactly one customer pool or prefer any eligible market capacity. Omit placement to prefer eligible private capacity." }, "PoolProposal": { "type": "object", "required": [ "id", "pool_id", "workload_id", "stage_id", "reason", "kind", "state", "envelope_version", "generation", "device_count", "expected_cost_micros", "approved_cost_micros", "created_at", "expires_at", "decided_at", "applied_at" ], "properties": { "id": { "type": "string", "minLength": 1 }, "pool_id": { "type": "string", "minLength": 1 }, "workload_id": { "type": "string", "minLength": 1 }, "stage_id": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "burst" ] }, "state": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "no_op", "applying", "applied" ] }, "envelope_version": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "generation": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "device_count": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "expected_cost_micros": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "approved_cost_micros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 1, "maximum": 9223372036854775807, "description": "Null until approval. Once approved, equals the immutable expected_cost_micros." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" } }, "description": "Retained burst approval intent for one submitted workload stage and generation. Approved records intent, applying means that generation claimed the approval, and applied requires an observed winning execution. Expiry blocks new dispatch but does not erase a winner dispatched before expiry. No supplier identity or quote secrets are returned." }, "PoolProposalsResponse": { "type": "object", "required": [ "pool_id", "proposals", "next_cursor" ], "properties": { "pool_id": { "type": "string" }, "proposals": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PoolProposal" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 2048 } } }, "PoolActionPolicyRequest": { "type": "object", "required": [ "kind", "level", "window_cron", "parallelism_cap" ], "properties": { "kind": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] }, "level": { "type": "string", "enum": [ "off", "recommend", "approve", "auto" ] }, "window_cron": { "type": "string", "maxLength": 256, "description": "Weekly UTC minute hour * * weekday. Minute, hour and weekday accept *, integer lists and inclusive ranges. No steps, names, macros, duplicate values or leading zeros. Weekday 0 is Sunday." }, "parallelism_cap": { "type": "integer", "minimum": 1, "maximum": 32 } }, "additionalProperties": false }, "PoolActionPolicy": { "type": "object", "required": [ "kind", "level", "window_cron", "parallelism_cap", "updated_at", "shadow_qualified", "shadow_producer_available" ], "properties": { "kind": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] }, "level": { "type": "string", "enum": [ "off", "recommend", "approve", "auto" ] }, "window_cron": { "type": "string", "maxLength": 256, "description": "Weekly UTC minute hour * * weekday. Minute, hour and weekday accept *, integer lists and inclusive ranges. No steps, names, macros, duplicate values or leading zeros. Weekday 0 is Sunday." }, "parallelism_cap": { "type": "integer", "minimum": 1, "maximum": 32 }, "updated_at": { "type": "string", "format": "date-time" }, "shadow_qualified": { "type": "boolean", "description": "A recent complete trusted cycle matches this policy configuration. This is evidence readiness, not execution authorization." }, "shadow_producer_available": { "type": "boolean", "default": false, "description": "True only when this server implements a trusted shadow producer for this kind. This does not establish automatic qualification." } } }, "PoolActionSettings": { "type": "object", "required": [ "pool_id", "kill_switch", "policies" ], "properties": { "pool_id": { "type": "string" }, "kill_switch": { "type": "boolean" }, "policies": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "$ref": "#/components/schemas/PoolActionPolicy" } } } }, "PoolActKillSwitchRequest": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "PoolShadowRun": { "type": "object", "required": [ "id", "pool_id", "kind", "window_cron", "parallelism_cap", "cycle_start", "cycle_end", "state", "ended_at", "trusted_hours", "elapsed_hours", "gap_hours", "would_have_acted", "producer_available", "qualifies_auto" ], "properties": { "id": { "type": "string" }, "pool_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] }, "window_cron": { "type": "string", "maxLength": 256, "description": "Weekly UTC minute hour * * weekday. Minute, hour and weekday accept *, integer lists and inclusive ranges. No steps, names, macros, duplicate values or leading zeros. Weekday 0 is Sunday." }, "parallelism_cap": { "type": "integer", "minimum": 1, "maximum": 32 }, "cycle_start": { "type": "string", "format": "date-time" }, "cycle_end": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "running", "completed" ] }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "trusted_hours": { "type": "integer", "minimum": 0, "maximum": 168 }, "elapsed_hours": { "type": "integer", "minimum": 0, "maximum": 168 }, "gap_hours": { "type": "integer", "minimum": 0, "maximum": 168 }, "would_have_acted": { "type": "integer", "minimum": 0, "description": "Sum of counterfactual action counts from trusted observations. Never measured savings or an applied-action count." }, "producer_available": { "type": "boolean" }, "qualifies_auto": { "type": "boolean", "description": "This exact cycle has 168 trusted hours, is completed and ended within 30 days. Current entitlement, policy, permissions and kill switch are checked separately." } }, "description": "A future 168-hour observation cycle. Missing capture is a gap, never fabricated evidence. Only idle reclaim currently has a trusted producer. Completed generic evidence cannot qualify automatic actions." }, "PoolShadowRuns": { "type": "object", "required": [ "pool_id", "runs", "next_cursor" ], "properties": { "pool_id": { "type": "string" }, "runs": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PoolShadowRun" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 2048 } } }, "PoolActOutcome": { "type": "object", "required": [ "source", "result", "recorded_at", "measured_saving_micros", "reported_saving_micros", "measurement_basis" ], "properties": { "source": { "type": "string", "enum": [ "server_observed", "customer_reported" ] }, "result": { "type": "string", "enum": [ "applied", "no_op", "failed" ] }, "recorded_at": { "type": "string", "format": "date-time" }, "measured_saving_micros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "description": "Observed platform-fee reduction only for the returned measurement basis. Null when unmeasured." }, "reported_saving_micros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "measurement_basis": { "type": [ "string", "null" ], "enum": [ "observed_platform_fee_reduction_30m_v1", null ], "description": "Observed Route platform-fee reduction over equal 30-minute windows. Not total infrastructure saving or a causal counterfactual." } }, "description": "Observed outcomes and customer reports are distinct. Missing measured savings stay null. Customer input never supplies server measurement." }, "PoolActProposal": { "type": "object", "required": [ "id", "pool_id", "recommendation_id", "reason", "kind", "level", "recommendation", "created_at", "expires_at", "state", "decided_at", "outcome" ], "properties": { "id": { "type": "string" }, "pool_id": { "type": "string" }, "recommendation_id": { "type": "string" }, "reason": { "type": "string" }, "kind": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] }, "level": { "type": "string", "enum": [ "approve", "auto" ] }, "recommendation": { "type": "object", "description": "Immutable server-retained recommendation evidence matching kind. No caller-provided action body." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "no_op", "applying", "uncertain", "applied", "failed" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/PoolActOutcome" }, { "type": "null" } ] } } }, "PoolActProposals": { "type": "object", "required": [ "pool_id", "proposals", "next_cursor" ], "properties": { "pool_id": { "type": "string" }, "proposals": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PoolActProposal" } }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 2048 } } }, "WorkloadFreeze": { "type": "object", "properties": { "id": { "type": "string" }, "workload_id": { "type": "string" }, "stage_id": { "type": "string" }, "manifest_id": { "type": "string" }, "reason": { "type": "string" }, "generation": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "requested", "releasing", "frozen", "resuming", "resumed", "failed" ] }, "requested_at": { "type": "string", "format": "date-time" }, "frozen_at": { "type": [ "string", "null" ], "format": "date-time" }, "retained_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "storage_charge_micros": { "type": [ "integer", "null" ], "description": "Null while retained storage is not separately metered. Do not infer a zero charge." }, "storage_billing_status": { "type": "string", "enum": [ "retained_storage_not_separately_metered" ] } }, "required": [ "id", "workload_id", "stage_id", "generation", "state", "requested_at", "frozen_at", "retained_bytes", "storage_charge_micros", "storage_billing_status" ], "description": "Saved checkpoint files and verified compute cleanup. Freeze and resume do not restore arbitrary process memory. The customer command must load its checkpoint." }, "PoolWaitTuningEvidence": { "type": "object", "properties": { "observed_hours": { "type": "integer", "minimum": 0, "const": 336 }, "completed_executions": { "type": "integer", "minimum": 0 }, "wait_seconds": { "type": "integer", "minimum": 0 }, "runtime_seconds": { "type": "integer", "minimum": 0 }, "burst_spent_micros": { "type": "integer", "minimum": 0 }, "policy_version": { "type": "integer", "minimum": 0 }, "observed_delay_pct": { "type": "number", "minimum": 0 }, "waiting_budget_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "current_alpha": { "type": "number", "minimum": 0 }, "proposed_alpha": { "type": "number", "minimum": 0 }, "method": { "type": "string", "const": "bounded_proportional_wait_v1" }, "history_from": { "type": "string", "format": "date-time" }, "history_to": { "type": "string", "format": "date-time" }, "source_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "observed_hours", "completed_executions", "wait_seconds", "runtime_seconds", "burst_spent_micros", "policy_version", "observed_delay_pct", "waiting_budget_pct", "current_alpha", "proposed_alpha", "method", "history_from", "history_to", "source_sha256" ] }, "PoolWaitTuningRecommendation": { "type": "object", "properties": { "kind": { "type": "string", "const": "wait_tuning" }, "level": { "type": "string", "const": "recommend" }, "risk": { "type": "string", "const": "high" }, "advisory_only": { "type": "boolean", "const": true }, "expected_savings_micros": { "type": "null" }, "expires_at": { "type": "string", "format": "date-time" }, "evidence": { "$ref": "#/components/schemas/PoolWaitTuningEvidence" } }, "required": [ "kind", "level", "risk", "advisory_only", "expected_savings_micros", "expires_at", "evidence" ], "description": "At most 25 percent adjustment based on 336 hours of actual Route coverage and completed settled executions. Applies to future waits. No counterfactual savings or universal delay guarantee." }, "PoolForecastQueue": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "retained_queue_immediate_start_v1" ] }, "observed_at": { "type": "string", "format": "date-time" }, "known_jobs": { "type": "integer", "minimum": 0 }, "unknown_jobs": { "type": "integer", "minimum": 0 }, "known_device_hours": { "type": "number", "minimum": 0 }, "added_device_hours": { "type": "number", "minimum": 0 }, "outside_horizon_device_hours": { "type": "number", "minimum": 0 } }, "required": [ "method", "observed_at", "known_jobs", "unknown_jobs", "known_device_hours", "added_device_hours", "outside_horizon_device_hours" ], "description": "Retained queued demand under an immediate-start scenario from the next complete hour. This is not a placement promise. Unknown runtimes remain a job count. Known device-hours equal added device-hours plus demand beyond the selected horizon." }, "BucketInput": { "type": "object", "additionalProperties": false, "required": [ "uri", "region", "bytes", "sha256", "credential_source" ], "properties": { "uri": { "type": "string", "description": "Canonical s3:// or gs:// object location without query parameters or credentials." }, "region": { "type": "string", "description": "Exact bucket region. policy.data_regions must contain only this region." }, "bytes": { "type": "integer", "minimum": 0, "maximum": 1099511627776 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "credential_source": { "type": "string", "enum": [ "team_webhook" ], "description": "Request temporary credentials synchronously from the configured team webhook. Credentials are never stored. The workload receives a sequential FIFO path in NODUS_INPUT_ and must consume it through EOF. Recovery restarts the stream and requests fresh credentials." } } }, "RLMetadata": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "environment_id", "mode", "model", "planned_tasks" ], "properties": { "schema_version": { "type": "integer", "const": 1, "description": "Required contract version. The server does not default an omitted version." }, "environment_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "maxLength": 64, "enum": [ "custom", "reasoning-gym", "swe-smith", "textarena", "miniwob", "officeqa", "appworld" ], "description": "Use custom for researcher-supplied training or evaluation without a catalog association, or choose an accepted catalog environment. This label does not establish runtime readiness or asset access." }, "mode": { "type": "string", "enum": [ "train", "evaluate" ], "description": "Custom workloads support train or evaluate. Catalog environments must support the selected mode. OfficeQA supports evaluate only." }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Customer-supplied model identifier. UTF-8 text, at most 256 bytes. Leading or trailing whitespace and control characters are rejected." }, "planned_tasks": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Planned logical task count. The customer command must apply this selection and limit. Recorded attempts may include retries." }, "example_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Catalog example the run was started from. Set by the example run endpoint and the console's Run button." }, "recipe": { "anyOf": [ { "$ref": "#/components/schemas/RLRecipeProvenance" }, { "type": "null" } ], "readOnly": true, "description": "Server-owned managed recipe identity. Custom workload submissions cannot set this field." } }, "allOf": [ { "if": { "properties": { "environment_id": { "const": "officeqa" } } }, "then": { "properties": { "mode": { "const": "evaluate" } } } } ], "description": "RL task association. Managed launches create the recipe provenance through /v1/rl-runs. For custom workloads, omit recipe and provide your own executable code, model setup, task limit and typed task events. Unknown and duplicate fields are rejected." }, "RLGradingResults": { "type": "object", "additionalProperties": false, "description": "Verified public grading receipts for one parent workload revision. Private cases, candidate source and child resource identities are excluded.", "required": [ "schema_version", "workload_id", "revision", "plan_sha256", "parent_status", "grading_cleanup_complete", "receipts" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "workload_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "plan_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "parent_status": { "type": "string", "description": "Current parent workload status, read with the receipts in one consistent snapshot." }, "grading_cleanup_complete": { "type": "boolean", "description": "Whether all grading attempts in this revision have completed cleanup. True for an empty receipt list. This does not establish parent cleanup, cleanup of other revisions or final billing settlement." }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/RLGradingReceipt" }, "description": "All admitted attempts in the requested revision, ordered by creation time and attempt identity. An empty list means no admitted attempts." } } }, "RLGradingReceipt": { "type": "object", "additionalProperties": false, "description": "A grading attempt bound to its candidate, private plan and execution manifest by hashes. A reward is present only after trusted grading completes. Infrastructure failure never supplies a model reward.", "required": [ "attempt_id", "request_id", "task_id", "candidate_sha256", "plan_sha256", "manifest_sha256", "state", "cleanup_complete" ], "properties": { "attempt_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "task_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "candidate_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "plan_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "pending", "completed", "infrastructure_failure" ] }, "reward": { "type": "number", "minimum": 0, "maximum": 1, "description": "Present only for a completed grading attempt. A zero reward is a measured grading result." }, "cleanup_complete": { "type": "boolean", "description": "Cleanup of this attempt is independent of its grading state and reward." }, "infrastructure_code": { "type": "string", "enum": [ "execution_lost", "execution_cancelled", "execution_failed", "output_incomplete", "grading_unavailable" ], "description": "Present only when state is infrastructure_failure." } } }, "RLEvent": { "type": "object", "additionalProperties": false, "required": [ "event_id", "phase", "task_id", "attempt", "kind" ], "properties": { "event_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable application event identity. UTF-8 text, at most 128 bytes. Leading or trailing whitespace and control characters are rejected." }, "phase": { "type": "string", "enum": [ "baseline", "training", "evaluation" ], "description": "Application-reported phase. A workload whose RL mode is evaluate cannot record training-phase events." }, "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Logical task identity within a stage and phase. UTF-8 text, at most 128 bytes. Leading or trailing whitespace and control characters are rejected." }, "attempt": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Application attempt number. Increment it for a genuinely repeated attempt. Infrastructure generation is separate and does not create a new logical attempt." }, "kind": { "type": "string", "enum": [ "task_started", "task_completed" ] }, "outcome": { "type": "string", "enum": [ "passed", "failed", "error" ], "description": "Required for task_completed and absent for task_started. Passed and failed describe a scored check. Error describes execution failure. Outcome is explicit and is never inferred from reward." }, "reward": { "type": "number", "description": "Optional finite reward on a completed attempt. Absence means no reward was reported. Zero is a reported reward and must not be treated as missing. Negative and nonbinary finite rewards are allowed." }, "duration_ms": { "type": "number", "minimum": 0, "description": "Optional finite nonnegative attempt duration in milliseconds on a completed attempt. Absence means not reported. Zero is valid." }, "message": { "type": "string", "maxLength": 1024, "description": "Short task activity message. At most 1024 UTF-8 bytes. Newline, carriage return and tab are allowed. Other control characters are rejected. Present only when explicitly emitted by the runner." }, "input": { "type": "string", "maxLength": 4096, "description": "Task input evidence. At most 4096 UTF-8 bytes. Newline, carriage return and tab are allowed. Other control characters are rejected. Present only when explicitly emitted by the runner." }, "output": { "type": "string", "maxLength": 4096, "description": "Agent output evidence. At most 4096 UTF-8 bytes. Newline, carriage return and tab are allowed. Other control characters are rejected. Present only when explicitly emitted by the runner." }, "verifier": { "type": "string", "maxLength": 4096, "description": "Verifier evidence. At most 4096 UTF-8 bytes. Newline, carriage return and tab are allowed. Other control characters are rejected. Present only when explicitly emitted by the runner." } }, "oneOf": [ { "properties": { "kind": { "const": "task_started" } }, "not": { "anyOf": [ { "required": [ "outcome" ] }, { "required": [ "reward" ] }, { "required": [ "duration_ms" ] } ] } }, { "properties": { "kind": { "const": "task_completed" } }, "required": [ "outcome" ] } ], "description": "A persisted application-reported task event. The encoded event is limited to 16 KiB. Stable event IDs are deduplicated within a workload, stage and execution generation. Reusing an identity with changed content in the same generation is rejected. A stage, generation, phase, task, attempt and kind may have only one immutable observation. Recovered generations retain separate observations, including identical content. Task completion is not workload completion, and these events do not change checkpoints or recovery progress. No task_started event is required before a task_completed event." }, "RLEventRow": { "type": "object", "additionalProperties": false, "required": [ "id", "stage_id", "generation", "received_at", "event" ], "properties": { "id": { "type": "string", "pattern": "^[0-9]+$", "description": "Server replay identity encoded as a decimal string to preserve integer precision. Treat it as an identifier. It is not the opaque after cursor or the application event_id." }, "stage_id": { "type": "string", "description": "Server-authorized workload stage that received the event." }, "generation": { "type": "integer", "description": "Execution generation authorized to report this observation. Retries within a generation retain their original row. Recovered generations receive distinct rows, even for identical application events." }, "received_at": { "type": "string", "format": "date-time", "description": "Server time when the event was first persisted." }, "event": { "$ref": "#/components/schemas/RLEvent" } }, "description": "An immutable replay row. Events are returned in ascending server replay order." }, "RLEventPage": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "events", "next_cursor", "has_more", "dropped_events", "truncated" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "events": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/RLEventRow" }, "description": "Available rows after the requested cursor, in ascending replay order. An empty array means no newer rows in this read." }, "next_cursor": { "type": "string", "maxLength": 64, "description": "Opaque exclusive cursor for the next request. Pass this value unchanged as after. It remains at the supplied position when no newer rows are returned. Do not derive a cursor from a row ID." }, "has_more": { "type": "boolean", "description": "More rows were available beyond this page in the current database snapshot. False does not mean the workload or task stream has ended." }, "dropped_events": { "type": "integer", "format": "int64", "minimum": 0, "description": "Sum of the highest reported loss counter for each stage and infrastructure generation. It is not an exact count of every event that may be absent. The counter can exceed a single generation limit." }, "truncated": { "type": "boolean", "description": "True when any delivery reported loss or hit a storage limit. Stored evidence is bounded to 100,000 events and 64 MiB of encoded event bodies per workload. Treat results as partial when true or dropped_events is nonzero. False does not prove lossless delivery after host loss." } }, "description": "Tenant-scoped persisted RL evidence with a consistent database snapshot for each page. While a run is active, keep polling the returned cursor even when has_more is false. After observing terminal workload status, perform a fresh drain before considering replay complete. A terminal workload status does not establish a task score." }, "RLRecipeProvenance": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" }, "version": { "type": "string", "maxLength": 64 }, "runtime_image": { "type": "string", "maxLength": 512, "description": "Immutable runtime image selected by Nodus for the managed recipe." }, "model_revision": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "config_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA256 of the exact runtime configuration bytes." }, "request_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Canonical reviewed request identity for durable retry." }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Original reviewed launch identity retained for retry after runtime rotation." } }, "required": [ "id", "version", "runtime_image", "model_revision", "config_sha256", "request_sha256", "review_token" ] }, "RLRecipeRequest": { "type": "object", "additionalProperties": false, "properties": { "recipe_id": { "type": "string", "default": "reasoning-gym-leg-counting", "enum": [ "reasoning-gym-leg-counting" ] }, "recipe_version": { "type": "string", "default": "1.0.0", "enum": [ "1.0.0" ] }, "mode": { "type": "string", "default": "evaluate", "enum": [ "evaluate", "train" ] }, "evaluation_tasks": { "type": "integer", "minimum": 4, "maximum": 64, "default": 16 }, "training_steps": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "max_cost_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 42 }, "include_traces": { "type": "boolean", "default": false, "description": "Opt in to prompt, model response and verifier text in live task events." } }, "required": [], "description": "Omitted fields use these defaults. Explicit null, unknown or repeated fields are rejected. Model, runtime and commands are selected by the recipe." }, "RLRunRequest": { "type": "object", "additionalProperties": false, "properties": { "recipe_id": { "type": "string", "default": "reasoning-gym-leg-counting", "enum": [ "reasoning-gym-leg-counting" ] }, "recipe_version": { "type": "string", "default": "1.0.0", "enum": [ "1.0.0" ] }, "mode": { "type": "string", "default": "evaluate", "enum": [ "evaluate", "train" ] }, "evaluation_tasks": { "type": "integer", "minimum": 4, "maximum": 64, "default": 16 }, "training_steps": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "max_cost_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 42 }, "include_traces": { "type": "boolean", "default": false, "description": "Opt in to prompt, model response and verifier text in live task events." }, "review_token": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "review_token" ] }, "RLRecipeOutput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ] }, "RLRecipePhase": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "enum": [ "baseline", "training", "evaluation", "export" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "label", "description" ] }, "RLRecipeDefaults": { "type": "object", "additionalProperties": false, "properties": { "evaluation_tasks": { "type": "integer", "minimum": 4, "maximum": 64, "default": 16 }, "training_steps": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "max_cost_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 42 } }, "required": [ "evaluation_tasks", "training_steps", "seed" ] }, "RLRecipeLimits": { "type": "object", "additionalProperties": false, "properties": { "comparison_tasks_min": { "type": "integer" }, "evaluation_tasks_min": { "type": "integer" }, "evaluation_tasks_max": { "type": "integer" }, "training_steps_min": { "type": "integer" }, "training_steps_max": { "type": "integer" } }, "required": [ "comparison_tasks_min", "evaluation_tasks_min", "evaluation_tasks_max", "training_steps_min", "training_steps_max" ] }, "RLEnvironment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "publisher": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "source_url": { "type": "string" }, "code_license": { "type": "string" }, "data_license": { "type": "string" }, "reward_type": { "type": "string" }, "reward_description": { "type": "string" }, "modes": { "type": "array", "items": { "type": "string", "enum": [ "train", "evaluate" ] } }, "launch": { "$ref": "#/components/schemas/RLEnvironmentLaunch" } }, "required": [ "id", "name", "publisher", "summary", "category", "source_url", "modes" ] }, "RLComparison": { "type": "object", "properties": { "baseline_pass_rate": { "type": "number" }, "evaluation_pass_rate": { "type": "number" }, "change_pp": { "type": "number", "description": "Evaluation minus baseline pass rate, in percentage points." }, "resolution_pp": { "type": "number", "description": "Smallest change the task count can show, 100 divided by the larger scored count." }, "comparable": { "type": "boolean" }, "measurable": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "comparable", "smallest_step", "different_attempt_counts", "different_tasks", "none_passed", "all_passed", "incomplete_events" ] }, "message": { "type": "string", "description": "Plain explanation of reason. Empty when reason is comparable." } }, "required": [ "baseline_pass_rate", "evaluation_pass_rate", "change_pp", "resolution_pp", "comparable", "measurable", "reason", "message" ] }, "RLPhaseSummary": { "type": "object", "properties": { "attempts": { "type": "integer", "description": "Finished attempts, scored or not." }, "scored": { "type": "integer", "description": "Attempts that passed or failed." }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "errors": { "type": "integer", "description": "Attempts that ended in an execution error. Not scored." }, "in_progress": { "type": "integer", "description": "Attempts started without a finish yet." }, "pass_rate": { "type": [ "number", "null" ], "description": "passed divided by scored, as a fraction. Null with nothing scored." }, "mean_reward": { "type": [ "number", "null" ], "description": "Mean reported reward of scored attempts. Null when none reported a reward." }, "reward_samples": { "type": "integer" } }, "required": [ "attempts", "scored", "passed", "failed", "errors", "in_progress", "pass_rate", "mean_reward", "reward_samples" ] }, "RLSummary": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "workload_id": { "type": "string" }, "phases": { "type": "object", "properties": { "baseline": { "$ref": "#/components/schemas/RLPhaseSummary" }, "training": { "$ref": "#/components/schemas/RLPhaseSummary" }, "evaluation": { "$ref": "#/components/schemas/RLPhaseSummary" } }, "required": [ "baseline", "training", "evaluation" ] }, "comparison": { "anyOf": [ { "$ref": "#/components/schemas/RLComparison" }, { "type": "null" } ], "description": "Null until both baseline and evaluation have scored attempts." }, "dropped_events": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "schema_version", "workload_id", "phases", "comparison", "dropped_events", "truncated" ] }, "RLEnvironmentExample": { "type": "object", "description": "One example you can run today. Every number was measured by running it.", "properties": { "id": { "type": "string", "description": "Stable identifier. Start this example with POST /v1/rl-environments/{environment}/examples/{id}/runs." }, "dataset": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "train", "evaluate" ] }, "summary": { "type": "string" }, "command": { "type": "string", "description": "Shell command. Run it through a shell, as the console does: it chains steps with &&." }, "baseline_pass_rate": { "type": "number", "description": "Held-out pass rate before training, as a fraction." }, "trained_pass_rate": { "type": "number" }, "measured_change_pp": { "type": "number", "description": "Measured change in percentage points after training." }, "runtime_minutes": { "type": "integer" } }, "required": [ "id", "dataset", "name", "command" ] }, "RLEnvironmentLaunch": { "type": "object", "description": "How to run this environment's examples. Absent when nothing is runnable yet.", "properties": { "image": { "type": "string" }, "model": { "type": "string" }, "peak_memory_gb": { "type": "number", "description": "GPU memory the examples were measured with. A run started from an example requests at least this much." }, "default_tasks": { "type": "integer", "minimum": 1 }, "measured_on": { "type": "string" }, "note": { "type": "string" }, "results": { "type": "array", "items": { "type": "string" }, "description": "Files each example writes and publishes for download." }, "examples": { "type": "array", "items": { "$ref": "#/components/schemas/RLEnvironmentExample" } } }, "required": [ "image", "model", "default_tasks", "examples" ] }, "RLRecipeDescriptor": { "type": "object", "additionalProperties": false, "properties": { "held_out_measures": {"type": "string"}, "id": { "type": "string" }, "version": { "type": "string" }, "environment_id": { "type": "string" }, "name": { "type": "string" }, "model": { "type": "string" }, "model_revision": { "type": "string" }, "taskset": { "type": "string" }, "modes": { "type": "array", "items": { "type": "string", "enum": [ "evaluate", "train" ] } }, "available": { "type": "boolean" }, "unavailable_reason": { "type": "string" }, "defaults": { "$ref": "#/components/schemas/RLRecipeDefaults" }, "limits": { "$ref": "#/components/schemas/RLRecipeLimits" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/RLRecipeOutput" } } }, "required": [ "held_out_measures", "id", "version", "environment_id", "name", "model", "model_revision", "taskset", "modes", "available", "defaults", "limits", "outputs" ] }, "RLRunEstimate": { "type": "object", "additionalProperties": false, "properties": { "estimator_version": { "type": "string" }, "catalog_version": { "type": "string" }, "profile_version": { "type": "string" }, "router_version": { "type": "string" }, "provenance": { "type": "string" }, "customer_price_version": { "type": "string" }, "status": { "type": "string", "enum": [ "estimated", "partial", "unavailable" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "execution_seconds": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "low": { "type": "number", "minimum": 0 }, "high": { "type": "number", "minimum": 0 } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "completion_seconds": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "low": { "type": "number", "minimum": 0 }, "high": { "type": "number", "minimum": 0 } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "compute_cost_usd": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "low": { "type": "number", "minimum": 0 }, "high": { "type": "number", "minimum": 0 } }, "required": [ "low", "high" ] }, { "type": "null" } ] } }, "required": [ "status", "reasons", "valid_until", "execution_seconds", "completion_seconds", "compute_cost_usd" ] }, "RLRunPreview": { "type": "object", "additionalProperties": false, "properties": { "recipe": { "$ref": "#/components/schemas/RLRecipeDescriptor" }, "configuration": { "$ref": "#/components/schemas/RLRecipeRequest" }, "review_token": { "type": "string", "maxLength": 64, "description": "Empty when the runtime is unavailable. Otherwise submit unchanged with the reviewed configuration." }, "phases": { "type": "array", "items": { "$ref": "#/components/schemas/RLRecipePhase" } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/RLRecipeOutput" } }, "estimate": { "$ref": "#/components/schemas/RLRunEstimate" }, "launchable": { "type": "boolean" }, "blocking_reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "recipe", "configuration", "review_token", "phases", "outputs", "estimate", "launchable", "blocking_reasons" ] }, "ConnectionCreate": { "type": "object", "additionalProperties": false, "required": [ "name", "kind", "secret" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "postgres", "neon", "supabase", "wandb" ] }, "secret": { "type": "string", "description": "Existing tenant secret name or ID. Credential values are accepted only by POST /v1/secrets." }, "scope": { "type": "string", "enum": [ "read", "write", "readwrite" ], "description": "Defaults to read for database kinds and write for wandb." }, "region": { "type": "string" }, "branch": { "type": "string" }, "entity": { "type": "string" }, "project": { "type": "string" }, "live_mode": { "type": "boolean", "default": false, "description": "Requires a current team administrator and wandb write or readwrite scope." } } }, "Connection": { "type": "object", "required": [ "id", "name", "kind", "secret_id", "secret_version", "scope", "egress_hosts", "live_mode", "verified_at", "created_at", "created_by" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "postgres", "neon", "supabase", "wandb" ] }, "scope": { "type": "string", "enum": [ "read", "write", "readwrite" ], "description": "Defaults to read for database kinds and write for wandb." }, "region": { "type": "string" }, "branch": { "type": "string" }, "entity": { "type": "string" }, "project": { "type": "string" }, "live_mode": { "type": "boolean", "default": false, "description": "Requires a current team administrator and wandb write or readwrite scope." }, "id": { "type": "string" }, "secret_id": { "type": "string" }, "secret_version": { "type": "integer", "minimum": 1 }, "egress_hosts": { "type": "array", "items": { "type": "string" } }, "verified_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } }, "ConnectionExport": { "type": "object", "properties": { "id": { "type": "string" }, "connection_id": { "type": "string" }, "asset_id": { "type": "string" }, "query_hash": { "type": "string" }, "branch": { "type": "string" }, "format": { "type": "string", "enum": [ "parquet", "csv" ] }, "row_count": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "pending", "running", "cleanup", "ready" ], "description": "Durable export state. Failed exports release this record after object cleanup." } } }, "WorkloadLink": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "wandb" ] }, "url": { "type": "string", "format": "uri", "description": "Validated HTTPS wandb run URL for the admitted entity and project." } }, "required": [ "kind", "url" ] }, "OutputDeclaration": { "type": "object", "additionalProperties": false, "required": [ "path" ], "properties": { "path": { "type": "string" }, "sink": { "$ref": "#/components/schemas/OutputSink" } } }, "OutputSink": { "type": "object", "additionalProperties": false, "required": [ "connection", "table" ], "properties": { "connection": { "type": "string" }, "table": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$", "description": "One PostgreSQL table identifier. The nodus_ prefix is reserved. Uppercase letters fold to lowercase." } } }, "ConnectionLoad": { "type": "object", "properties": { "id": { "type": "string" }, "workload_id": { "type": "string" }, "stage": { "type": "string" }, "generation": { "type": "integer" }, "name": { "type": "string" }, "table": { "type": "string" }, "rows": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "loading", "loaded", "failed" ] }, "sink_error": { "type": "string" } } }, "CheckpointPreparationSummary": { "type": "object", "properties": { "stage_id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "ready", "failed", "cancelled" ] }, "proposed_integration": { "type": "string", "enum": [ "none", "hf-trainer-v1" ], "description": "Present after source preparation. hf-trainer-v1 is a proposed adapter that still requires validation when training starts. none retains application-managed checkpoints." }, "ready_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OperationDefinition": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string", "const": "v1" }, "name": { "type": "string", "description": "Compatible hosted agent tool name." }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true }, "annotations": { "type": "object", "additionalProperties": true }, "required_scope": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "version", "name", "description", "inputSchema", "annotations", "required_scope", "transports" ] }, "OperationCatalog": { "type": "object", "required": [ "version", "operations" ], "properties": { "version": { "type": "string", "const": "v1" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationDefinition" } } } }, "OperationWorkloadsListArguments": { "additionalProperties": false, "properties": { "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "offset": { "maximum": 2147483647, "minimum": 0, "type": "integer" }, "scope": { "description": "Omitted or empty scope uses the existing team default.", "enum": [ "team", "mine", "" ], "type": "string" } }, "required": [], "type": "object" }, "OperationWorkloadsGetArguments": { "additionalProperties": false, "properties": { "workload_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workload_id" ], "type": "object" }, "OperationWorkloadsEventsArguments": { "additionalProperties": false, "properties": { "after": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "workload_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workload_id" ], "type": "object" }, "OperationWorkloadsLogsArguments": { "additionalProperties": false, "properties": { "workload_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workload_id" ], "type": "object" }, "OperationWorkloadsOutputsArguments": { "additionalProperties": false, "properties": { "workload_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workload_id" ], "type": "object" }, "OperationWorkloadsValidateArguments": { "additionalProperties": false, "properties": { "workload": { "description": "Customer HTTP workload request. Preserve the user's command, image and resources.", "properties": { "outcome": { "properties": { "max_cost_usd": { "deprecated": true, "minimum": 0, "type": [ "number", "null" ] } }, "type": "object" } }, "type": "object" } }, "required": [ "workload" ], "type": "object" }, "OperationWorkspacesCapabilitiesArguments": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "OperationWorkspacesListArguments": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "OperationWorkspacesGetArguments": { "additionalProperties": false, "properties": { "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id" ], "type": "object" }, "OperationWorkspacesCreateArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "workspace": { "additionalProperties": false, "description": "Workspace configuration. Read get_workspace_capabilities first for valid GPU models, counts and environments.", "properties": { "disk_gb": { "description": "Optional runtime disk in GB.", "maximum": 2048, "minimum": 0, "type": "integer" }, "environment": { "description": "Software environment id from get_workspace_capabilities, such as pytorch-cuda.", "type": "string" }, "gpu": { "description": "GPU model from get_workspace_capabilities, such as A100 or RTX 4090.", "type": "string" }, "gpu_count": { "maximum": 8, "minimum": 1, "type": "integer" }, "gpu_form_factor": { "description": "Optional GPU form factor.", "enum": [ "pcie", "sxm", "nvl" ], "type": "string" }, "gpu_memory_gb": { "description": "Memory per GPU in GB, matching the chosen model.", "exclusiveMinimum": 0, "type": "number" }, "host_memory_gb": { "description": "Optional minimum system RAM in GB.", "maximum": 4096, "minimum": 0, "type": "number" }, "name": { "description": "Workspace name shown in the console.", "maxLength": 128, "minLength": 1, "type": "string" }, "runtime_id": { "description": "Runtime id from get_workspace_capabilities, when the workspace uses a specific image.", "type": "string" }, "size_gb": { "description": "Saved project storage in GB for /workspace. Omit to use the deployment's capacity.", "exclusiveMinimum": 0, "type": "number" }, "ssh_authorized_key": { "description": "Optional SSH public keys, one per line. Team members' account keys are admitted too.", "maxLength": 8192, "type": "string" }, "vcpus": { "description": "Optional minimum vCPUs.", "maximum": 256, "minimum": 0, "type": "integer" } }, "required": [ "name", "gpu", "gpu_count", "gpu_memory_gb" ], "type": "object" } }, "required": [ "workspace", "idempotency_key" ], "type": "object" }, "OperationWorkspacesConfigureArguments": { "additionalProperties": false, "properties": { "configuration": { "additionalProperties": false, "description": "The complete new configuration.", "properties": { "disk_gb": { "description": "Optional runtime disk in GB.", "maximum": 2048, "minimum": 0, "type": "integer" }, "environment": { "description": "Software environment id from get_workspace_capabilities, such as pytorch-cuda.", "type": "string" }, "gpu": { "description": "GPU model from get_workspace_capabilities, such as A100 or RTX 4090.", "type": "string" }, "gpu_count": { "maximum": 8, "minimum": 1, "type": "integer" }, "gpu_form_factor": { "description": "Optional GPU form factor.", "enum": [ "pcie", "sxm", "nvl" ], "type": "string" }, "gpu_memory_gb": { "description": "Memory per GPU in GB, matching the chosen model.", "exclusiveMinimum": 0, "type": "number" }, "host_memory_gb": { "description": "Optional minimum system RAM in GB.", "maximum": 4096, "minimum": 0, "type": "number" }, "name": { "description": "Workspace name shown in the console.", "maxLength": 128, "minLength": 1, "type": "string" }, "runtime_id": { "description": "Runtime id from get_workspace_capabilities, when the workspace uses a specific image.", "type": "string" }, "size_gb": { "description": "Saved project storage in GB for /workspace. Omit to use the deployment's capacity.", "exclusiveMinimum": 0, "type": "number" }, "ssh_authorized_key": { "description": "Optional SSH public keys, one per line. Team members' account keys are admitted too.", "maxLength": 8192, "type": "string" }, "vcpus": { "description": "Optional minimum vCPUs.", "maximum": 256, "minimum": 0, "type": "integer" } }, "required": [ "name", "gpu", "gpu_count", "gpu_memory_gb" ], "type": "object" }, "configuration_revision": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "configuration_revision", "configuration", "idempotency_key" ], "type": "object" }, "OperationWorkspacesStartArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "idempotency_key" ], "type": "object" }, "OperationWorkspacesDeleteArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "idempotency_key" ], "type": "object" }, "OperationWorkspacesStopArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "session_id": { "maxLength": 256, "minLength": 1, "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "session_id", "idempotency_key" ], "type": "object" }, "OperationWorkspacesConnectArguments": { "additionalProperties": false, "properties": { "tool": { "enum": [ "editor", "notebook", "ssh" ], "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "tool" ], "type": "object" }, "OperationWorkspacesRunArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "job": { "additionalProperties": false, "properties": { "budget_usd": { "description": "Spending cap for this job.", "exclusiveMinimum": 0, "type": "number" }, "command": { "description": "Shell command run in /workspace.", "maxLength": 8192, "minLength": 1, "type": "string" }, "gpu": { "description": "GPU model, defaulting to the workspace's.", "type": "string" }, "gpu_count": { "maximum": 8, "minimum": 1, "type": "integer" }, "gpu_memory_gb": { "exclusiveMinimum": 0, "type": "number" } }, "required": [ "command", "budget_usd" ], "type": "object" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "job", "idempotency_key" ], "type": "object" }, "OperationWorkspacesWorkloadsArguments": { "additionalProperties": false, "properties": { "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id" ], "type": "object" }, "OperationWorkspacesSessionsArguments": { "additionalProperties": false, "properties": { "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id" ], "type": "object" }, "OperationWorkspacesScheduleArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "schedule": { "additionalProperties": false, "properties": { "ready_by": { "format": "date-time", "type": "string" }, "stop_at": { "format": "date-time", "type": "string" } }, "required": [ "ready_by" ], "type": "object" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "schedule", "idempotency_key" ], "type": "object" }, "OperationWorkspacesUnscheduleArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "workspace_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workspace_id", "idempotency_key" ], "type": "object" }, "OperationWorkloadsSubmitArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 256, "minLength": 1, "pattern": "^[^\\r\\n]+$", "type": "string" }, "workload": { "description": "Customer HTTP workload request. Preserve the user's command, image and resources.", "properties": { "outcome": { "properties": { "max_cost_usd": { "deprecated": true, "minimum": 0, "type": [ "number", "null" ] } }, "type": "object" } }, "type": "object" } }, "required": [ "workload", "idempotency_key" ], "type": "object" }, "OperationWorkloadsCancelArguments": { "additionalProperties": false, "properties": { "workload_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "workload_id" ], "type": "object" }, "OperationArguments": { "description": "The generic endpoint accepts the union of operation argument shapes. OpenAPI validation alone cannot correlate the operation path parameter with the request body. Clients must validate against the selected operation inputSchema from the catalog. The server enforces that selected schema and rejects unknown arguments. Workload values also follow WorkloadPayload and ordinary submission validation.", "anyOf": [ { "$ref": "#/components/schemas/OperationWorkloadsListArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsGetArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsEventsArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsLogsArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsOutputsArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsValidateArguments" }, { "$ref": "#/components/schemas/OperationRunDraftGetArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsSubmitArguments" }, { "$ref": "#/components/schemas/OperationWorkloadsCancelArguments" }, { "$ref": "#/components/schemas/OperationRunDraftUpdateArguments" }, { "$ref": "#/components/schemas/OperationSandboxesCapabilitiesArguments" }, { "$ref": "#/components/schemas/OperationSandboxesTemplatesArguments" }, { "$ref": "#/components/schemas/OperationSandboxesCreateArguments" }, { "$ref": "#/components/schemas/OperationSandboxesListArguments" }, { "$ref": "#/components/schemas/OperationSandboxesGetArguments" }, { "$ref": "#/components/schemas/OperationSandboxesExecArguments" }, { "$ref": "#/components/schemas/OperationSandboxesExecGetArguments" }, { "$ref": "#/components/schemas/OperationSandboxesExecOutputArguments" }, { "$ref": "#/components/schemas/OperationSandboxesExecCancelArguments" }, { "$ref": "#/components/schemas/OperationSandboxesFilesArguments" }, { "$ref": "#/components/schemas/OperationSandboxesSleepArguments" }, { "$ref": "#/components/schemas/OperationSandboxesWakeArguments" }, { "$ref": "#/components/schemas/OperationSandboxesTerminateArguments" }, { "$ref": "#/components/schemas/OperationAgentsCreateArguments" }, { "$ref": "#/components/schemas/OperationAgentsUpdateArguments" }, { "$ref": "#/components/schemas/OperationAgentsListArguments" }, { "$ref": "#/components/schemas/OperationAgentsGetArguments" }, { "$ref": "#/components/schemas/OperationAgentsSubmitArguments" }, { "$ref": "#/components/schemas/OperationAgentsRunsArguments" }, { "$ref": "#/components/schemas/OperationAgentsRunGetArguments" }, { "$ref": "#/components/schemas/OperationAgentsRunStepsArguments" }, { "$ref": "#/components/schemas/OperationAgentsSignalArguments" }, { "$ref": "#/components/schemas/OperationAgentsPauseArguments" }, { "$ref": "#/components/schemas/OperationAgentsResumeArguments" }, { "$ref": "#/components/schemas/OperationAgentsRunRetryArguments" }, { "$ref": "#/components/schemas/OperationAgentsRunCancelArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesCapabilitiesArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesListArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesGetArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesCreateArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesConfigureArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesStartArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesDeleteArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesStopArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesConnectArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesRunArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesWorkloadsArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesSessionsArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesScheduleArguments" }, { "$ref": "#/components/schemas/OperationWorkspacesUnscheduleArguments" } ] }, "WorkloadValidationResult": { "type": "object", "required": [ "valid", "submitted", "workload", "message" ], "properties": { "valid": { "type": "boolean", "const": true }, "submitted": { "type": "boolean", "const": false }, "workload": { "$ref": "#/components/schemas/WorkloadPayload" }, "message": { "type": "string" } } }, "OperationRunDraftGetArguments": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "OperationRunDraftUpdateArguments": { "additionalProperties": false, "properties": { "expected_revision": { "maximum": 9007199254740990, "minimum": 0, "type": "integer" }, "patch": { "additionalProperties": false, "maxProperties": 13, "minProperties": 1, "not": { "properties": { "gpu_count": { "type": "integer" }, "total_gpu_count": { "type": "integer" } }, "required": [ "gpu_count", "total_gpu_count" ] }, "properties": { "checkpoint_paths": { "anyOf": [ { "items": { "description": "Relative path of at most 256 UTF-8 bytes without parent traversal, wildcards, backslashes, NUL, carriage returns or line feeds.", "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 8, "type": "array" }, { "type": "null" } ] }, "command": { "anyOf": [ { "description": "At most 4000 UTF-8 bytes. Empty strings are preserved.", "maxLength": 4000, "type": "string" }, { "type": "null" } ] }, "data_regions": { "anyOf": [ { "items": { "description": "The server additionally enforces a limit of 128 UTF-8 bytes and rejects whitespace, commas and control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, { "type": "null" } ] }, "disk_gb": { "anyOf": [ { "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ] }, "gpu": { "anyOf": [ { "description": "At most 256 UTF-8 bytes. Empty strings are preserved.", "maxLength": 256, "type": "string" }, { "type": "null" } ] }, "gpu_count": { "anyOf": [ { "maximum": 8, "minimum": 1, "type": "integer" }, { "type": "null" } ] }, "image": { "anyOf": [ { "description": "At most 256 UTF-8 bytes. Empty strings are preserved.", "maxLength": 256, "type": "string" }, { "type": "null" } ] }, "max_cost_usd": { "anyOf": [ { "deprecated": true, "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ] }, "memory_gb": { "anyOf": [ { "maximum": 1024, "minimum": 1, "type": "number" }, { "type": "null" } ] }, "name": { "anyOf": [ { "description": "At most 120 UTF-8 bytes. Empty strings are preserved.", "maxLength": 120, "type": "string" }, { "type": "null" } ] }, "result_paths": { "anyOf": [ { "items": { "description": "Relative path of at most 256 UTF-8 bytes without parent traversal, wildcards, backslashes, NUL, carriage returns or line feeds.", "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 8, "type": "array" }, { "type": "null" } ] }, "total_gpu_count": { "anyOf": [ { "description": "Total GPUs across the allocation. Clear gpu_count when setting this field. Saving this preference does not establish available capacity.", "maximum": 2048, "minimum": 1, "type": "integer" }, { "type": "null" } ] }, "vcpus": { "anyOf": [ { "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ] } }, "type": "object" } }, "required": [ "expected_revision", "patch" ], "type": "object" }, "RunDraftValues": { "type": "object", "maxProperties": 12, "additionalProperties": false, "description": "Explicitly saved partial form values. Missing fields have no saved value. Reading or editing a draft does not authorize spending.", "properties": { "checkpoint_paths": { "items": { "description": "Relative path of at most 256 UTF-8 bytes without parent traversal, wildcards, backslashes, NUL, carriage returns or line feeds.", "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 8, "type": "array" }, "command": { "description": "At most 4000 UTF-8 bytes. Empty strings are preserved.", "maxLength": 4000, "type": "string" }, "gpu": { "description": "At most 256 UTF-8 bytes. Empty strings are preserved.", "maxLength": 256, "type": "string" }, "gpu_count": { "maximum": 8, "minimum": 1, "type": "integer" }, "image": { "description": "At most 256 UTF-8 bytes. Empty strings are preserved.", "maxLength": 256, "type": "string" }, "max_cost_usd": { "type": "number", "deprecated": true, "description": "Deprecated compatibility field. Customer spending limits are not enforced." }, "memory_gb": { "maximum": 1024, "minimum": 1, "type": "number" }, "name": { "description": "At most 120 UTF-8 bytes. Empty strings are preserved.", "maxLength": 120, "type": "string" }, "result_paths": { "items": { "description": "Relative path of at most 256 UTF-8 bytes without parent traversal, wildcards, backslashes, NUL, carriage returns or line feeds.", "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 8, "type": "array" }, "vcpus": { "exclusiveMinimum": 0, "type": "number" }, "disk_gb": { "exclusiveMinimum": 0, "type": "number" }, "data_regions": { "items": { "description": "The server additionally enforces a limit of 128 UTF-8 bytes and rejects whitespace, commas and control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true }, "total_gpu_count": { "type": "integer", "minimum": 1, "maximum": 2048 } }, "allOf": [ { "not": { "required": [ "gpu_count", "total_gpu_count" ] } } ] }, "RunDraft": { "type": "object", "required": [ "revision", "values", "updated_at" ], "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "values": { "$ref": "#/components/schemas/RunDraftValues" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ManagedAgentCreate": { "type": "object", "additionalProperties": false, "properties": { "attempt_budget_usd": { "type": ["number", "null"], "minimum": 0.000001, "maximum": 1000000, "multipleOf": 0.000001, "description": "Optional fixed reservation for each new attempt in USD, in whole microdollars. Omission preserves the legacy allocation policy. Increasing worker concurrency does not reduce this amount." }, "name": { "type": "string", "description": "Deployment name. An omitted built-in assistant name is generated from the idempotency key." }, "entrypoint": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*$" }, "budget_usd": { "type": "number", "description": "Deprecated compatibility field. Customer spending limits are not enforced.", "deprecated": true }, "template": { "type": "string" }, "source": { "type": "object", "additionalProperties": false, "properties": { "asset_id": { "type": "string" } }, "required": [ "asset_id" ] }, "bootstrap": { "$ref": "#/components/schemas/SandboxBootstrap" }, "setup": { "type": "string", "maxLength": 8192 }, "secrets": { "type": "array", "items": { "type": "string" } }, "network_permissions": { "type": "array", "items": { "type": "string", "enum": [ "github", "python_packages", "node_packages", "openai", "anthropic" ] }, "uniqueItems": true }, "requirements": { "$ref": "#/components/schemas/Requirements" }, "min_workers": { "type": "integer", "minimum": 0, "default": 0 }, "max_workers": { "type": "integer", "minimum": 1, "maximum": 100, "default": 4 }, "policy": { "$ref": "#/components/schemas/SandboxPolicy" }, "assistant_template": { "type": "string", "enum": [ "nodus:claude-assistant-v1", "nodus:claude-assistant-v2" ], "description": "Qualified built-in assistant from assistant_templates in the managed model catalog. Supplies its installed entrypoint and environment. No project, setup command or provider credential is required." }, "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "maxLength": 128, "description": "Qualified Messages model accepted for this revision. Provider credentials stay in Nodus." }, "model_max_output_tokens": { "type": "integer", "minimum": 1, "description": "Per-call output bound for hosted model access. Omission uses the selected model maximum from the current catalog. An explicit value must fit that model. Accepted revisions retain their resolved limit." } }, "allOf": [ { "if": { "required": [ "assistant_template" ] }, "then": { "required": [ "model" ] }, "else": { "required": [ "name", "entrypoint" ] } } ], "description": "Custom code supplies a name and entrypoint. A qualified built-in assistant supplies assistant_template and model, with optional name and worker limits. The built-in assistant rejects source, bootstrap, setup, secrets, network permissions and policy overrides." }, "ManagedModelRates": { "type": "object", "additionalProperties": false, "required": [ "input_micros_per_million", "output_micros_per_million" ], "properties": { "input_micros_per_million": { "type": "integer", "format": "int64", "minimum": 1, "description": "Customer price for uncached input, in USD micros per million tokens." }, "output_micros_per_million": { "type": "integer", "format": "int64", "minimum": 1, "description": "Customer price for output including reasoning, in USD micros per million tokens." }, "cache_read_micros_per_million": { "type": "integer", "format": "int64", "minimum": 0, "description": "Customer price for cached input reads. Omission means this cache bucket is not qualified, not free." }, "cache_write_5m_micros_per_million": { "type": "integer", "format": "int64", "minimum": 0, "description": "Customer price for five-minute cache creation. Omission means this bucket is not qualified." }, "cache_write_1h_micros_per_million": { "type": "integer", "format": "int64", "minimum": 0, "description": "Customer price for one-hour cache creation. Omission means this bucket is not qualified." } }, "description": "Published customer rates include the 12.5 percent service markup and round upward for display. One USD micro is 0.000001 USD. Each token belongs to one billing bucket. Actual charges apply the markup to the aggregate selected model supplier cost and round upward once. When rates_are_maximum is true, rates are the maximum across eligible models and the actual charge may be lower." }, "ManagedModelPublic": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "protocol", "price_version", "rates", "max_output_tokens", "streaming" ], "properties": { "id": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "minLength": 7, "maxLength": 128, "description": "Model ID returned by this account’s managed model catalog." }, "label": { "type": "string" }, "protocol": { "type": "string", "enum": [ "messages", "chat_completions" ] }, "price_version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "rates": { "$ref": "#/components/schemas/ManagedModelRates" }, "rates_are_maximum": { "type": "boolean", "description": "When true, published rates are maximum customer rates across eligible models. Actual charges use the selected model supplier cost plus 12.5 percent." }, "max_output_tokens": { "type": "integer", "minimum": 1, "maximum": 200000 }, "streaming": { "type": "boolean", "const": false } }, "description": "An account-qualified model and its published customer pricing. No credentials or private routing configuration are returned." }, "ManagedModelCatalog": { "type": "object", "additionalProperties": false, "required": [ "enabled", "models", "billing", "currency", "assistant_templates" ], "properties": { "enabled": { "type": "boolean", "description": "True when at least one model is granted to this account." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedModelPublic" }, "description": "Qualified models sorted by ID. Empty for accounts without a configured grant." }, "billing": { "type": "string", "const": "nodus_credits" }, "currency": { "type": "string", "const": "USD" }, "assistant_templates": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAssistantTemplate" }, "description": "Built-in assistants available on the qualified runtime. Empty until account, compute, model and exact image qualifications all pass." } } }, "ManagedAssistantTemplate": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "protocol", "model_ids", "default_output_tokens" ], "properties": { "id": { "type": "string", "enum": ["nodus:claude-assistant-v1", "nodus:claude-assistant-v2"] }, "label": { "type": "string" }, "protocol": { "type": "string", "const": "messages" }, "model_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Models qualified for this installed assistant." }, "default_output_tokens_by_model": { "type": "object", "additionalProperties": {"type": "integer", "minimum": 1}, "description": "Default output allowance for each available catalog model." }, "default_output_tokens": { "type": "integer", "minimum": 1, "description": "Largest default among available models. Use default_output_tokens_by_model for a selected model." } }, "description": "An assistant qualified for the account and the exact tools image. Empty discovery prevents launching into incompatible runtimes." }, "ManagedModelUsage": { "type": "object", "additionalProperties": false, "required": [ "input_tokens", "output_tokens", "cached_input_tokens", "cache_creation_5m_input_tokens", "cache_creation_1h_input_tokens" ], "properties": { "input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Total input including all cache buckets. Uncached input is the remainder after subtracting the cache buckets." }, "output_tokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Total output including reasoning tokens." }, "cached_input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Input tokens read from cache." }, "cache_creation_5m_input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Input tokens written with a five-minute cache lifetime." }, "cache_creation_1h_input_tokens": { "type": "integer", "format": "int64", "minimum": 0, "description": "Input tokens written with a one-hour cache lifetime." } }, "description": "Normalized, verified accounting counters. These receipt counters differ from the native usage object returned by a completion request." }, "ManagedModelReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "model", "price_version", "state", "reserved_micros", "charge_micros", "usage", "created_at" ], "properties": { "id": { "type": "string" }, "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "minLength": 7, "maxLength": 128, "description": "Model ID returned by this account’s managed model catalog." }, "price_version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "state": { "type": "string", "enum": [ "running", "succeeded", "failed", "unknown" ], "description": "Running and unknown keep their reservation. Succeeded posts the verified charge. Failed records a definitive rejection without a model charge." }, "reserved_micros": { "type": "integer", "format": "int64", "minimum": 1, "description": "Original spending reservation in USD micros. It is held only while state is running or unknown." }, "charge_micros": { "type": "integer", "format": "int64", "minimum": 0, "description": "Settled customer charge in USD micros. Zero until successful settlement. Model charges are separate from compute and saved storage." }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/ManagedModelUsage" }, { "type": "object", "maxProperties": 0 } ], "description": "Verified normalized usage after successful settlement. Empty for running, unknown and failed requests." }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "description": "Present for succeeded and failed requests." } }, "description": "Durable billing evidence scoped to the authenticated account. Prompts, model answers, credentials and private pricing are not included." }, "ManagedModelReplay": { "type": "object", "additionalProperties": false, "required": [ "error", "receipt" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "const": "model_request_already_accepted" }, "message": { "type": "string" } } }, "receipt": { "$ref": "#/components/schemas/ManagedModelReceipt" } }, "description": "The original request is not executed again. This response does not replay the generated answer." }, "ManagedModelChatMessage": { "type": "object", "additionalProperties": false, "required": [ "role" ], "anyOf": [ { "required": [ "content" ] }, { "required": [ "tool_calls" ] } ], "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "additionalProperties": true } } ], "description": "Text or text blocks only. Null is used for an assistant function call without text. Images and audio are not supported." }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string" }, "arguments": { "type": "string", "description": "Function arguments encoded as a JSON string." } }, "additionalProperties": true } }, "additionalProperties": true } }, "tool_call_id": { "type": "string" } }, "description": "Native chat-completions message. Use role and content combinations supported by the catalog model." }, "ManagedModelFunctionTool": { "type": "object", "required": [ "type", "function" ], "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true }, "strict": { "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true, "description": "Customer-defined function only. The response can request a function call. Nodus does not execute the function through this endpoint." }, "ManagedModelMessagesContent": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "tool_use", "tool_result", "thinking", "redacted_thinking" ] }, "text": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "tool_use_id": { "type": "string" }, "content": { "$ref": "#/components/schemas/ManagedModelMessagesContent" }, "is_error": { "type": "boolean" }, "thinking": { "type": "string" }, "signature": { "type": "string" }, "data": { "type": "string" }, "cache_control": { "type": "object", "description": "Native cache settings for eligible blocks. Cache usage must have qualified catalog prices.", "additionalProperties": true } }, "additionalProperties": true, "description": "Use the selected model’s native fields for this block type. Only text, customer function calls/results and reasoning blocks are supported. Nested tool results have the same text-only restriction." } } ], "description": "Text or native text/function/reasoning blocks. Media and provider-hosted tool blocks are not supported." }, "ManagedModelMessagesMessage": { "type": "object", "additionalProperties": false, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "$ref": "#/components/schemas/ManagedModelMessagesContent" } }, "description": "Native Messages turn. Supply system instructions through the top-level system field." }, "ManagedModelMessagesTool": { "type": "object", "required": [ "name", "input_schema" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true }, "cache_control": { "type": "object", "additionalProperties": true } }, "additionalProperties": true, "description": "Customer-defined tool. Omit type or use custom. Provider-hosted tools are not admitted." }, "ManagedModelChatCompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "minLength": 7, "maxLength": 128, "description": "Model ID returned by this account’s managed model catalog." }, "messages": { "type": "array", "minItems": 1, "maxItems": 1024, "items": { "$ref": "#/components/schemas/ManagedModelChatMessage" } }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 200000, "description": "Must not exceed max_output_tokens from the model catalog. Omission uses that catalog limit." }, "stream": { "type": "boolean", "const": false, "default": false, "description": "Only nonstreaming requests are admitted." }, "temperature": { "type": "number", "description": "Native model sampling setting. Model-specific validation still applies." }, "top_p": { "type": "number" }, "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ManagedModelFunctionTool" } }, "tool_choice": { "description": "Native selection of a customer-defined function tool. Provider-hosted tools are not supported.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "max_completion_tokens": { "type": "integer", "minimum": 1, "maximum": 200000, "description": "Must not exceed max_output_tokens from the model catalog. Omission uses that catalog limit." }, "stop": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "seed": { "type": "integer" }, "response_format": { "type": "object", "additionalProperties": true, "description": "Native text response formatting. This does not enable media output." }, "reasoning_effort": { "type": "string" }, "parallel_tool_calls": { "type": "boolean" } }, "not": { "required": [ "max_tokens", "max_completion_tokens" ] }, "description": "Bounded native chat-completions request for a catalog model using chat_completions. The JSON body is limited to 1 MiB. Choose max_tokens or max_completion_tokens, not both. Unsupported top-level fields, streaming, media and provider-hosted tools are refused. Native model-specific validation also applies." }, "ManagedModelMessagesRequest": { "type": "object", "additionalProperties": false, "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "minLength": 7, "maxLength": 128, "description": "Model ID returned by this account’s managed model catalog." }, "messages": { "type": "array", "minItems": 1, "maxItems": 1024, "items": { "$ref": "#/components/schemas/ManagedModelMessagesMessage" } }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 200000, "description": "Must not exceed max_output_tokens from the model catalog. Omission uses that catalog limit." }, "stream": { "type": "boolean", "const": false, "default": false, "description": "Only nonstreaming requests are admitted." }, "temperature": { "type": "number", "description": "Native model sampling setting. Model-specific validation still applies." }, "top_p": { "type": "number" }, "tools": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/ManagedModelMessagesTool" } }, "tool_choice": { "description": "Native selection of a customer-defined function tool. Provider-hosted tools are not supported.", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "system": { "$ref": "#/components/schemas/ManagedModelMessagesContent" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "thinking": { "type": "object", "additionalProperties": true, "description": "Native reasoning configuration within the catalog output limit. Reasoning tokens count toward billed output." }, "metadata": { "type": "object", "additionalProperties": true } }, "description": "Bounded native Messages request for a catalog model using messages. The JSON body is limited to 1 MiB. An omitted max_tokens uses the catalog output limit. Unsupported top-level fields, streaming, media and provider-hosted tools are refused. Native model-specific validation also applies." }, "ManagedModelCompletionResponse": { "type": "object", "required": [ "model", "usage" ], "properties": { "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "minLength": 7, "maxLength": 128, "description": "Model ID returned by this account’s managed model catalog." }, "usage": { "type": "object", "additionalProperties": true, "description": "Verified usage in the selected model’s native response format. Read the billing receipt for normalized counters and the settled charge." } }, "additionalProperties": true, "description": "Nonstreaming native response with its model field replaced by the Nodus catalog ID. Other fields follow the selected protocol, such as content or choices. The caller must save the answer. It is not retained or replayed by the billing ledger." }, "ManagedAgent": { "type": "object", "additionalProperties": false, "properties": { "attempt_budget_usd": { "type": ["number", "null"], "minimum": 0.000001, "maximum": 1000000, "multipleOf": 0.000001, "description": "Fixed attempt reservation from the current accepted revision. Absent for the legacy allocation policy." }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "current_revision": { "type": "integer" }, "budget_usd": { "type": "number", "deprecated": true, "description": "Deprecated compatibility field. Customer spending limits are not enforced." }, "cost_usd": { "type": "number" }, "reserved_usd": { "type": "number" }, "min_workers": { "type": "integer" }, "max_workers": { "type": "integer" }, "workers": { "type": "object", "additionalProperties": false, "properties": { "starting": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "idle": { "type": "integer", "minimum": 0 }, "stopping": { "type": "integer", "minimum": 0 }, "unresolved": { "type": "integer", "minimum": 0 }, "ready": { "type": "integer", "minimum": 0, "description": "Unused current-revision workers with successful setup, available to compatible independent work." }, "waiting": { "type": "integer", "minimum": 0, "description": "Workers retained by waiting logical runs." } }, "required": [] }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" }, "queued": { "type": "integer", "minimum": 0, "description": "Accepted queued or recovering runs." }, "assistant_template": { "type": "string", "enum": [ "nodus:claude-assistant-v1", "nodus:claude-assistant-v2" ], "description": "Qualified built-in assistant from assistant_templates in the managed model catalog. Supplies its installed entrypoint and environment. No project, setup command or provider credential is required." }, "model": { "type": "string", "pattern": "^nodus:[A-Za-z0-9._:-]+$", "maxLength": 128, "description": "Qualified Messages model accepted for this revision. Provider credentials stay in Nodus." }, "model_max_output_tokens": { "type": "integer", "minimum": 1, "description": "Per-call output bound for hosted model access. Omission uses the selected model maximum from the current catalog. An explicit value must fit that model. Accepted revisions retain their resolved limit." } }, "required": [ "id", "name", "status", "current_revision", "cost_usd", "reserved_usd", "workers" ] }, "ManagedAgentRun": { "type": "object", "additionalProperties": false, "properties": { "attempt_budget_usd": { "type": ["number", "null"], "minimum": 0.000001, "maximum": 1000000, "multipleOf": 0.000001, "description": "Immutable attempt reservation accepted for this logical run. Absent for the legacy allocation policy." }, "recovery_policy": { "type": "string", "enum": [ "checkpoint-v1" ], "description": "Accepted application-state recovery policy. Omitted for revisions with explicit file recovery." }, "checkpoint_id": { "type": "string", "description": "Current committed application-state checkpoint, including an empty baseline. This identity can differ from the latest capture reported by checkpoint_status." }, "checkpoint_status": { "type": "string", "enum": [ "pending", "ready", "committed", "failed" ], "description": "Latest capture status. Ready means uploaded files are verified but not yet committed with the journal boundary." }, "checkpoint_error": { "type": "string", "description": "Failure code for the latest application-state capture. A failed capture does not replace committed recovery state." }, "last_checkpoint_at": { "type": "string", "format": "date-time", "description": "Commit time of the current useful application-state checkpoint. Omitted for empty baselines and runs without saved state." }, "payload_expired": { "type": "boolean" }, "id": { "type": "string" }, "agent_id": { "type": "string" }, "revision": { "type": "integer" }, "session": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "starting", "running", "waiting", "recovering", "blocked", "completed", "cancelled" ] }, "reason": { "type": "string" }, "input": {}, "result": {}, "deadline": { "type": "string", "format": "date-time" }, "next_wake_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "sandbox_id": { "type": "string" }, "exec_id": { "type": "string" }, "attempt": { "type": "integer" }, "segment": { "type": "integer" }, "startup": { "$ref": "#/components/schemas/SandboxStartup" }, "group_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "description": "Present for a task belonging to a static agent group." }, "task_key": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "depends_on": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "description": "Immutable prerequisite task keys within the group." } }, "required": [ "id", "agent_id", "revision", "status" ] }, "ManagedAgentObservations": { "type": "object", "additionalProperties": false, "properties": { "schema_version": { "type": "string", "enum": [ "managed-agent-observations-v1" ], "description": "Version of these lifecycle observation semantics." }, "agent_id": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time", "description": "Database observation time for this response. Subsequent pages can observe newer state." }, "logical_runs": { "$ref": "#/components/schemas/ManagedAgentLogicalRunCounts", "description": "Counts of logical run statuses across all revisions of this definition. Running does not establish productive activity." }, "allocations": { "$ref": "#/components/schemas/ManagedAgentAllocationObservations", "description": "Retained attempt and resource evidence. Counts can overlap and do not establish current healthy capacity." }, "productive_active_agents": { "type": "null", "description": "Null because retained lifecycle records do not independently measure productive agent activity." }, "productive_active_agents_status": { "type": "string", "enum": [ "measurement_unavailable" ], "description": "Whether productive agent concurrency is independently measured." }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRunObservation" } }, "next_after": { "type": "string", "description": "Cursor for the next page in ascending run ID order, or an empty string. Each page has its own database snapshot." } }, "required": [ "schema_version", "agent_id", "observed_at", "logical_runs", "allocations", "productive_active_agents", "productive_active_agents_status", "runs", "next_after" ] }, "ManagedAgentLogicalRunCounts": { "type": "object", "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0 }, "queued": { "type": "integer", "minimum": 0 }, "starting": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "waiting": { "type": "integer", "minimum": 0 }, "recovering": { "type": "integer", "minimum": 0 }, "blocked": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 } }, "required": [ "total", "queued", "starting", "running", "waiting", "recovering", "blocked", "completed", "cancelled" ] }, "ManagedAgentAllocationObservations": { "type": "object", "additionalProperties": false, "properties": { "total_attempts": { "type": "integer", "minimum": 0 }, "open_attempts": { "type": "integer", "minimum": 0, "description": "Attempts not recorded closed, including admitted, starting, running and draining allocations." }, "starting_attempts": { "type": "integer", "minimum": 0 }, "draining_attempts": { "type": "integer", "minimum": 0 }, "warm_attempts": { "type": "integer", "minimum": 0, "description": "Open attempts not assigned to a logical run." }, "unresolved_attempts": { "type": "integer", "minimum": 0, "description": "Attempts with uncertain creation or retained candidate cleanup and accounting incidents." }, "cleanup_pending_attempts": { "type": "integer", "minimum": 0, "description": "Attempts still open or lacking settled cleanup, including retained resource, lease, allowance or storage liability. Includes active attempts and does not mean stop was requested." }, "unreleased_instances": { "type": "integer", "minimum": 0, "description": "Known instance records without removal evidence. This is not a healthy instance count." } }, "required": [ "total_attempts", "open_attempts", "starting_attempts", "draining_attempts", "warm_attempts", "unresolved_attempts", "cleanup_pending_attempts", "unreleased_instances" ] }, "ManagedAgentRunObservation": { "type": "object", "additionalProperties": false, "properties": { "run_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "queued", "starting", "running", "waiting", "recovering", "blocked", "completed", "cancelled" ] }, "attempt_count": { "type": "integer", "minimum": 0 }, "submitted_at": { "type": "string", "format": "date-time" }, "first_allocation_created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest retained attempt creation time. A warm allocation can predate submission." }, "first_boot_observed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest retained sandbox boot binding. A warm boot can predate submission." }, "first_driver_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First recorded driver process start. This is not proof of useful task work." }, "first_session_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First durable driver session receipt." }, "first_step_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First retained completed step receipt. A completed step does not establish accepted task output." }, "first_useful_command_at": { "type": "null", "description": "Null because useful work requires independent workload evidence." }, "first_useful_command_status": { "type": "string", "enum": [ "measurement_unavailable" ], "description": "Whether useful command activity is independently measured." }, "result_committed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Logical result commit time for completed runs. Customer acceptance is checked separately." }, "cleanup_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest attempt closure when every associated attempt and retained resource liability is settled. Otherwise null." }, "open_attempts": { "type": "integer", "minimum": 0, "description": "Attempts not recorded closed, including admitted, starting, running and draining allocations." }, "unresolved_attempts": { "type": "integer", "minimum": 0, "description": "Attempts with uncertain creation or retained candidate cleanup and accounting incidents." }, "cleanup_pending_attempts": { "type": "integer", "minimum": 0, "description": "Attempts still open or lacking settled cleanup, including retained resource, lease, allowance or storage liability. Includes active attempts and does not mean stop was requested." }, "unreleased_instances": { "type": "integer", "minimum": 0, "description": "Known instance records without removal evidence. This is not a healthy instance count." } }, "required": [ "run_id", "revision", "status", "attempt_count", "submitted_at", "first_allocation_created_at", "first_boot_observed_at", "first_driver_started_at", "first_session_started_at", "first_step_completed_at", "first_useful_command_at", "first_useful_command_status", "result_committed_at", "cleanup_completed_at", "open_attempts", "unresolved_attempts", "cleanup_pending_attempts", "unreleased_instances" ] }, "ManagedAgentSubmit": { "type": "object", "additionalProperties": false, "properties": { "input": {}, "session": { "type": "string" }, "deadline": { "type": "string", "format": "date-time" } }, "required": [ "input" ] }, "ManagedAgentSignal": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "input": {} }, "required": [ "name", "input" ] }, "ManagedAgentUpdate": { "type": "object", "additionalProperties": false, "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "definition": { "$ref": "#/components/schemas/ManagedAgentCreate" } }, "required": [ "expected_revision", "definition" ] }, "SandboxFileOperation": { "type": "object", "additionalProperties": false, "properties": { "operation": { "type": "string", "enum": [ "list", "stat", "read", "write" ] }, "path": { "type": "string" }, "data": { "type": "string", "format": "byte" }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0, "maximum": 262144 }, "expected_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "create_parents": { "type": "boolean" } }, "required": [ "operation", "path" ] }, "ManagedAgentRevision": { "type": "object", "additionalProperties": false, "properties": { "agent_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "definition": { "$ref": "#/components/schemas/ManagedAgentCreate" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "agent_id", "revision", "definition", "created_at" ] }, "OperationSandboxesCapabilitiesArguments": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "OperationSandboxesTemplatesArguments": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "OperationSandboxesCreateArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox": { "additionalProperties": false, "description": "Customer sandbox create request. Use verified assets or a connected GitHub source and secret references.", "properties": { "bootstrap": { "anyOf": [ { "additionalProperties": false, "properties": { "dotfiles": { "type": "string" }, "ref": { "type": "string" }, "repo": { "type": "string" }, "setup": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "budget_usd": { "deprecated": true, "description": "Compatibility field. Customer spending limits are not enforced.", "type": "number" }, "connections": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "continuity": { "anyOf": [ { "additionalProperties": false, "properties": { "interval_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mode": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "from_snapshot": { "type": "string" }, "image": { "type": "string" }, "lifecycle": { "anyOf": [ { "additionalProperties": false, "properties": { "idle_timeout_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_lifetime_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "on_idle": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "name": { "type": "string" }, "network_permissions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "outcome": { "anyOf": [ { "additionalProperties": false, "properties": { "complete_by": { "type": "string" }, "max_cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "type": "object" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "additionalProperties": false, "properties": { "data_regions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "egress_allow": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "network": { "type": "string" }, "secret_refs": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, { "type": "null" } ] }, "profile": { "type": "string" }, "requirements": { "additionalProperties": false, "properties": { "compute_class": { "type": "string" }, "dataset_bytes": { "type": "integer" }, "disk_gb": { "type": "number" }, "expected_runtime_hours": { "type": "number" }, "gpu": { "type": "string" }, "gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "gpu_interconnect": { "type": "string" }, "model": { "type": "string" }, "notes": { "type": "string" }, "optimization": { "type": "string" }, "peak_memory_gb": { "type": "number" }, "total_gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "vcpus": { "type": "number" }, "distribution": { "anyOf": [ { "additionalProperties": false, "properties": { "config_file": { "type": "string" }, "diloco": { "anyOf": [ { "additionalProperties": false, "properties": { "islands": { "type": "integer" }, "local_steps": { "type": "integer" }, "outer_learning_rate": { "type": "number" }, "outer_momentum": { "type": "number" }, "synchronization_timeout_seconds": { "type": "integer" }, "version": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "framework": { "type": "string" }, "geography": { "type": "string" }, "mode": { "type": "string" }, "processes_per_node": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "node_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "reservation": { "anyOf": [ { "additionalProperties": false, "properties": { "cron": { "type": "string" }, "max_concurrent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_idle_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "min_ready": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "release": { "type": "string" }, "wake_slo_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, { "type": "null" } ] }, "secrets": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "service": { "anyOf": [ { "additionalProperties": false, "properties": { "command": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "health_path": { "type": "string" }, "port": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "setup": { "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "asset_id": { "type": "string" }, "cache": { "type": "boolean" }, "image": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "stuck_after_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "template": { "type": "string" }, "wake": { "type": "string" }, "workspace": { "anyOf": [ { "additionalProperties": false, "properties": { "mount": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, { "type": "null" } ] } }, "type": "object" } }, "required": [ "sandbox", "idempotency_key" ], "type": "object" }, "OperationSandboxesListArguments": { "additionalProperties": false, "properties": { "cursor": { "maxLength": 256, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "name": { "maxLength": 256, "type": "string" }, "status": { "maxLength": 256, "type": "string" } }, "required": [], "type": "object" }, "OperationSandboxesGetArguments": { "additionalProperties": false, "properties": { "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id" ], "type": "object" }, "OperationSandboxesExecArguments": { "additionalProperties": false, "properties": { "command": { "additionalProperties": false, "description": "Customer sandbox exec request, including command and optional cwd, env and timeout.", "properties": { "cols": { "type": "integer" }, "command": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "cwd": { "type": "string" }, "env": { "additionalProperties": { "type": "string" }, "type": [ "object", "null" ] }, "rows": { "type": "integer" }, "stdin": { "type": "boolean" }, "timeout_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tty": { "type": "boolean" } }, "type": "object" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "command", "idempotency_key" ], "type": "object" }, "OperationSandboxesExecGetArguments": { "additionalProperties": false, "properties": { "exec_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "exec_id" ], "type": "object" }, "OperationSandboxesExecOutputArguments": { "additionalProperties": false, "properties": { "after": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "exec_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "limit": { "maximum": 16, "minimum": 1, "type": "integer" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "exec_id" ], "type": "object" }, "OperationSandboxesExecCancelArguments": { "additionalProperties": false, "properties": { "exec_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "exec_id", "idempotency_key" ], "type": "object" }, "OperationSandboxesFilesArguments": { "additionalProperties": false, "properties": { "file": { "additionalProperties": false, "description": "File helper request with operation, relative path and the existing bounded chunk fields.", "properties": { "create_parents": { "type": "boolean" }, "data": { "type": "string" }, "expected_sha256": { "type": "string" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "operation": { "type": "string" }, "path": { "type": "string" } }, "type": "object" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "file", "idempotency_key" ], "type": "object" }, "OperationSandboxesSleepArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "idempotency_key" ], "type": "object" }, "OperationSandboxesWakeArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "idempotency_key" ], "type": "object" }, "OperationSandboxesTerminateArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "sandbox_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "sandbox_id", "idempotency_key" ], "type": "object" }, "OperationAgentsCreateArguments": { "additionalProperties": false, "properties": { "agent": { "additionalProperties": false, "description": "Customer managed-agent definition with name, entrypoint, verified source and worker settings.", "properties": { "assistant_template": { "type": "string" }, "attempt_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bootstrap": { "anyOf": [ { "additionalProperties": false, "properties": { "dotfiles": { "type": "string" }, "ref": { "type": "string" }, "repo": { "type": "string" }, "setup": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "budget_usd": { "deprecated": true, "description": "Compatibility field. Customer spending limits are not enforced.", "type": "number" }, "entrypoint": { "type": "string" }, "max_workers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "min_workers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "model": { "type": "string" }, "model_max_output_tokens": { "type": "integer", "description": "Per-call output bound for hosted model access. Omission uses the selected model maximum from the current catalog. An explicit value must fit that model. Accepted revisions retain their resolved limit." }, "name": { "type": "string" }, "network_permissions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "policy": { "anyOf": [ { "additionalProperties": false, "properties": { "data_regions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "egress_allow": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "network": { "type": "string" }, "secret_refs": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, { "type": "null" } ] }, "requirements": { "additionalProperties": false, "properties": { "compute_class": { "type": "string" }, "dataset_bytes": { "type": "integer" }, "disk_gb": { "type": "number" }, "expected_runtime_hours": { "type": "number" }, "gpu": { "type": "string" }, "gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "gpu_interconnect": { "type": "string" }, "model": { "type": "string" }, "notes": { "type": "string" }, "optimization": { "type": "string" }, "peak_memory_gb": { "type": "number" }, "total_gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "vcpus": { "type": "number" }, "distribution": { "anyOf": [ { "additionalProperties": false, "properties": { "config_file": { "type": "string" }, "diloco": { "anyOf": [ { "additionalProperties": false, "properties": { "islands": { "type": "integer" }, "local_steps": { "type": "integer" }, "outer_learning_rate": { "type": "number" }, "outer_momentum": { "type": "number" }, "synchronization_timeout_seconds": { "type": "integer" }, "version": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "framework": { "type": "string" }, "geography": { "type": "string" }, "mode": { "type": "string" }, "processes_per_node": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "node_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "secrets": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "setup": { "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "asset_id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "template": { "type": "string" } }, "type": "object" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } }, "required": [ "agent", "idempotency_key" ], "type": "object" }, "OperationAgentsUpdateArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "update": { "additionalProperties": false, "description": "Customer update request containing expected_revision and definition.", "properties": { "definition": { "additionalProperties": false, "description": "The complete new deployment definition.", "properties": { "assistant_template": { "type": "string" }, "attempt_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bootstrap": { "anyOf": [ { "additionalProperties": false, "properties": { "dotfiles": { "type": "string" }, "ref": { "type": "string" }, "repo": { "type": "string" }, "setup": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "budget_usd": { "deprecated": true, "description": "Compatibility field. Customer spending limits are not enforced.", "type": "number" }, "entrypoint": { "type": "string" }, "max_workers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "min_workers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "model": { "type": "string" }, "model_max_output_tokens": { "type": "integer", "description": "Per-call output bound for hosted model access. Omission uses the selected model maximum from the current catalog. An explicit value must fit that model. Accepted revisions retain their resolved limit." }, "name": { "type": "string" }, "network_permissions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "policy": { "anyOf": [ { "additionalProperties": false, "properties": { "data_regions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "egress_allow": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "network": { "type": "string" }, "secret_refs": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, { "type": "null" } ] }, "requirements": { "additionalProperties": false, "properties": { "compute_class": { "type": "string" }, "dataset_bytes": { "type": "integer" }, "disk_gb": { "type": "number" }, "expected_runtime_hours": { "type": "number" }, "gpu": { "type": "string" }, "gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "gpu_interconnect": { "type": "string" }, "model": { "type": "string" }, "notes": { "type": "string" }, "optimization": { "type": "string" }, "peak_memory_gb": { "type": "number" }, "total_gpu_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "vcpus": { "type": "number" }, "distribution": { "anyOf": [ { "additionalProperties": false, "properties": { "config_file": { "type": "string" }, "diloco": { "anyOf": [ { "additionalProperties": false, "properties": { "islands": { "type": "integer" }, "local_steps": { "type": "integer" }, "outer_learning_rate": { "type": "number" }, "outer_momentum": { "type": "number" }, "synchronization_timeout_seconds": { "type": "integer" }, "version": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "framework": { "type": "string" }, "geography": { "type": "string" }, "mode": { "type": "string" }, "processes_per_node": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "node_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "secrets": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "setup": { "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "asset_id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "template": { "type": "string" } }, "type": "object" }, "expected_revision": { "minimum": 1, "type": "integer" } }, "required": [ "expected_revision", "definition" ], "type": "object" } }, "required": [ "agent_id", "update", "idempotency_key" ], "type": "object" }, "OperationAgentsListArguments": { "additionalProperties": false, "properties": { "after": { "maxLength": 256, "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [], "type": "object" }, "OperationAgentsGetArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "agent_id" ], "type": "object" }, "OperationAgentsSubmitArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "run": { "additionalProperties": false, "description": "Run submission with input, optional session and deadline.", "properties": { "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "input": {}, "session": { "type": "string" } }, "type": "object" } }, "required": [ "agent_id", "run", "idempotency_key" ], "type": "object" }, "OperationAgentsRunsArguments": { "additionalProperties": false, "properties": { "after": { "maxLength": 256, "type": "string" }, "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "agent_id" ], "type": "object" }, "OperationAgentsRunGetArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "run_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "agent_id", "run_id" ], "type": "object" }, "OperationAgentsRunStepsArguments": { "additionalProperties": false, "properties": { "after": { "maxLength": 256, "type": "string" }, "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "run_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "agent_id", "run_id" ], "type": "object" }, "OperationAgentsSignalArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "run_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "signal": { "additionalProperties": false, "description": "Signal request with name and optional input.", "properties": { "input": {}, "name": { "type": "string" } }, "type": "object" } }, "required": [ "agent_id", "run_id", "signal", "idempotency_key" ], "type": "object" }, "OperationAgentsPauseArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } }, "required": [ "agent_id", "idempotency_key" ], "type": "object" }, "OperationAgentsResumeArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" } }, "required": [ "agent_id", "idempotency_key" ], "type": "object" }, "OperationAgentsRunRetryArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "run_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "agent_id", "run_id", "idempotency_key" ], "type": "object" }, "OperationAgentsRunCancelArguments": { "additionalProperties": false, "properties": { "agent_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "pattern": "^[!-~]{1,200}$", "type": "string" }, "run_id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,128}$", "type": "string" } }, "required": [ "agent_id", "run_id", "idempotency_key" ], "type": "object" }, "SandboxStartup": { "type": "object", "properties": { "stage": { "type": "string" }, "acquisition_ms": { "type": "integer", "minimum": 0 }, "image_preparation_ms": { "type": "integer", "minimum": 0 }, "project_download_ms": { "type": "integer", "minimum": 0 }, "project_materialization_ms": { "type": "integer", "minimum": 0 }, "checkpoint_download_ms": { "type": "integer", "minimum": 0 }, "checkpoint_restore_ms": { "type": "integer", "minimum": 0 }, "setup_ms": { "type": "integer", "minimum": 0 }, "driver_start_ms": { "type": "integer", "minimum": 0 }, "image_cache_reads": { "type": "integer", "minimum": 0 }, "image_cache_hits": { "type": "integer", "minimum": 0 }, "project_prefetched": { "type": "boolean" }, "checkpoint_prefetched": { "type": "boolean" }, "warm_claimed": { "type": "boolean" }, "warm_miss_reason": { "type": "string" } }, "description": "Measured startup stages. Missing durations are unobserved. Overlapping durations must not be added into elapsed latency." }, "CloudOnboardingInput": { "type": "object", "additionalProperties": false, "properties": { "provider": { "type": "string", "enum": [ "aws", "gcp" ] }, "name": { "type": "string", "maxLength": 100, "description": "Optional name, trimmed on submission. Empty or omitted values become AWS or Google Cloud for the selected provider. At most 100 UTF-8 bytes." }, "regions": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z]{2}-[a-z]+-[0-9]+$" }, "maxItems": 100, "uniqueItems": true, "default": [], "description": "Commercial AWS regions only. GovCloud and China partitions are not supported by this connection flow. Omitted, null, or empty discovers all enabled account regions. A nonempty list restricts collection. Region order does not affect idempotency. GCP requires an empty list." }, "project_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{4,28}[a-z0-9]$", "description": "Google Cloud project ID. Required for GCP and omitted for AWS." }, "billing_location": { "type": "string", "enum": [ "US", "EU" ], "description": "Location of the dedicated Google Cloud billing dataset. Defaults to US for GCP and is omitted for AWS." } }, "required": [ "provider" ], "allOf": [ { "if": { "properties": { "provider": { "const": "gcp" } } }, "then": { "required": [ "project_id" ], "properties": { "regions": { "maxItems": 0 } } }, "else": { "properties": { "project_id": false, "billing_location": false } } } ] }, "CloudOnboardingSession": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Opaque server-generated setup identity." }, "provider": { "type": "string", "enum": [ "aws", "gcp" ] }, "name": { "type": "string" }, "regions": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 100, "description": "AWS enabled account regions when empty. Always an array and empty for Google Cloud." }, "role_name": { "type": "string", "pattern": "^(NodusObserve-[a-f0-9]{32})?$", "description": "Prepared AWS role name. Empty for Google Cloud." }, "state": { "type": "string", "enum": [ "pending", "completed", "cancelled" ] }, "expires_at": { "type": "string", "format": "date-time" }, "connection_id": { "type": "string", "description": "Present after completion. A later disconnect does not remove this completion receipt." }, "revision": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "project_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{4,28}[a-z0-9]$", "description": "Google Cloud project ID. Required for GCP and omitted for AWS." }, "billing_location": { "type": "string", "enum": [ "US", "EU" ], "description": "Location of the dedicated Google Cloud billing dataset. Defaults to US for GCP and is omitted for AWS." }, "project_number": { "type": "string", "pattern": "^[1-9][0-9]{5,19}$", "description": "Google Cloud project number verified for this connection." } }, "required": [ "id", "provider", "name", "regions", "role_name", "state", "expires_at", "revision", "created_at" ], "description": "Setup expires after 24 hours. Expired pending records remain readable with their original expiry and cannot complete. Only unexpired pending records appear in the active list." }, "CloudOnboardingAction": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "open_provider", "unavailable", "expired", "completed", "cancelled" ] }, "url": { "type": "string", "format": "uri", "description": "Prepared AWS CloudFormation approval or Google Cloud Shell URL, present for open_provider." }, "message": { "type": "string", "description": "Explanation when guided setup is unavailable." }, "setup_command": { "type": "string", "description": "Reviewable Google Cloud Shell setup command. Present only for pending GCP setup. Does not contain credentials." } }, "required": [ "type" ] }, "CloudOnboardingResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/CloudOnboardingSession" }, "next_action": { "$ref": "#/components/schemas/CloudOnboardingAction" }, "connection": { "$ref": "#/components/schemas/CloudObservationConnection" } }, "required": [ "session", "next_action" ], "description": "Connection is included after completion while it remains connected. A completed receipt never reconnects a disconnected account." }, "CloudOnboardingSessionList": { "type": "object", "additionalProperties": false, "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CloudOnboardingSession" }, "maxItems": 5 } }, "required": [ "sessions" ] }, "CloudOnboardingVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "account_id": { "type": "string", "pattern": "^[0-9]{12}$", "description": "AWS account ID from the stack outputs. This is a hint until Nodus verifies the exact session role using STS." }, "project_number": { "type": "string", "pattern": "^[1-9][0-9]{5,19}$", "description": "Google Cloud project number printed by setup. Nodus verifies it against the saved project ID and observation access before completing setup." } }, "oneOf": [ { "required": [ "account_id" ], "not": { "required": [ "project_number" ] } }, { "required": [ "project_number" ], "not": { "required": [ "account_id" ] } } ] }, "CloudObservationConfig": { "type": "object", "additionalProperties": false, "properties": { "provider": { "type": "string", "enum": [ "aws", "gcp", "azure" ] }, "name": { "type": "string" }, "role_arn": { "type": "string" }, "project_id": { "type": "string" }, "billing_table": { "type": "string" }, "billing_location": { "type": "string" }, "billing_scope": { "type": "string" }, "directory_id": { "type": "string" }, "subscription_id": { "type": "string" }, "client_id": { "type": "string" }, "regions": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "name" ], "description": "Account identity and read scope. Fields depend on the provider. Credentials are never returned." }, "CloudObservationConnection": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "aws", "gcp", "azure" ] }, "scope": { "type": "string" }, "config": { "$ref": "#/components/schemas/CloudObservationConfig" }, "state": { "type": "string", "enum": [ "pending", "collecting", "ready", "partial", "error" ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "provider", "scope", "config", "state", "last_attempt_at", "last_success_at", "created_at" ] }, "CloudConnectionList": { "type": "object", "additionalProperties": false, "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationConnection" } }, "can_connect": { "type": "boolean", "description": "Whether credential storage is configured. This does not confer administrator access or prove guided AWS availability." }, "collection_interval_minutes": { "type": "integer", "const": 60 }, "connection_limit": { "type": "integer", "const": 200 } }, "required": [ "connections", "can_connect", "collection_interval_minutes", "connection_limit" ] }, "CloudConnectionSetup": { "type": "object", "additionalProperties": false, "properties": { "aws_principal_arn": { "type": "string" }, "aws_external_id": { "type": "string" }, "guided_aws_available": { "type": "boolean", "description": "Guided AWS setup is configured and its published access template matches this release. This does not verify access to the customer's AWS account." }, "guided_aws_unavailable_reason": { "type": "string" }, "mode": { "type": "string", "enum": [ "observe" ] }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "resource_inventory", "virtual_machine_inventory", "cpu", "network", "disk_io", "account_costs" ] } }, "guided_gcp_available": { "type": "boolean", "description": "Guided Google Cloud setup is configured. This does not verify access to the customer project." }, "guided_gcp_unavailable_reason": { "type": "string" }, "google_signin_available": { "type": "boolean", "description": "The Google Web OAuth client and keyless observation identity are configured." } }, "required": [ "aws_principal_arn", "aws_external_id", "guided_aws_available", "guided_aws_unavailable_reason", "mode", "capabilities", "guided_gcp_available", "guided_gcp_unavailable_reason" ] }, "CloudObservationCoverage": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "description": "Source collection state. May be empty before its first collection." }, "source": { "type": "string" }, "message": { "type": "string" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "status", "source", "message", "observed_at" ] }, "CloudObservedResource": { "type": "object", "additionalProperties": false, "properties": { "provider_id": { "type": "string" }, "resource_type": { "type": "string" }, "service": { "type": "string" }, "category": { "type": "string" }, "scope": { "type": "string" }, "group": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "region": { "type": "string" }, "zone": { "type": "string" }, "state": { "type": "string" }, "machine_type": { "type": "string" }, "gpu_type": { "type": "string" }, "vcpus": { "type": [ "number", "null" ] }, "memory_gb": { "type": [ "number", "null" ] }, "gpu_count": { "type": [ "integer", "null" ] }, "tags": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "required": [ "id", "name", "kind", "region", "state", "machine_type", "vcpus", "memory_gb", "gpu_count", "tags" ], "description": "Customer cloud resource metadata. Missing measurements remain null. Discovery does not enroll the resource for workload execution." }, "CloudDailyObservation": { "type": "object", "additionalProperties": false, "properties": { "day": { "type": "string", "format": "date" }, "value": { "type": [ "number", "null" ] } }, "required": [ "day", "value" ] }, "CloudObservationBreakdown": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "value": { "type": "number" } }, "required": [ "name", "value" ] }, "CloudObservationForecast": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string" }, "method": { "type": "string" }, "message": { "type": "string" }, "history_days": { "type": "integer" }, "points": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudDailyObservation" } }, "total": { "type": [ "number", "null" ] }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } }, "by_region": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } }, "by_project": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } } }, "required": [ "status", "method", "message", "history_days", "points", "total" ], "description": "Usage-continuation projection from measured history. Does not predict credit exhaustion or compare workload execution prices." }, "CloudObservationSeries": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "history": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudDailyObservation" } }, "total": { "type": [ "number", "null" ] }, "breakdown": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } }, "by_region": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } }, "by_project": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" } }, "forecast": { "$ref": "#/components/schemas/CloudObservationForecast" }, "measured_total": { "type": "number", "description": "Sum of available observed costs in an aggregate window. A missing complete total means the subtotal has incomplete coverage." }, "by_provider": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationBreakdown" }, "description": "Observed spending allocated to cloud providers. Currencies and unavailable costs are not combined." } }, "required": [ "key", "label", "unit", "history", "total", "breakdown", "forecast" ] }, "CloudObservationReport": { "type": "object", "additionalProperties": false, "properties": { "discovery": { "$ref": "#/components/schemas/CloudObservationCoverage" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/CloudObservationSeries" } }, "resources": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CloudObservedResource" } }, "inventory": { "$ref": "#/components/schemas/CloudObservationCoverage" }, "performance": { "$ref": "#/components/schemas/CloudObservationCoverage" }, "billing": { "$ref": "#/components/schemas/CloudObservationCoverage" }, "gpu_inventory": { "$ref": "#/components/schemas/CloudGPUInventory" } }, "required": [ "discovery", "from", "to", "series", "resources", "inventory", "performance", "billing", "gpu_inventory" ] }, "CloudConnectionReportResponse": { "type": "object", "additionalProperties": false, "properties": { "connection": { "$ref": "#/components/schemas/CloudObservationConnection" }, "report": { "$ref": "#/components/schemas/CloudObservationReport" }, "gpu_history": { "type": "array", "items": { "$ref": "#/components/schemas/CloudGPUHistory" }, "maxItems": 30, "description": "History for the selected 7 or 30 UTC days, including today, from the current connected scope. Retention is up to 90 days. This window differs from report history, which ends yesterday." } }, "required": [ "connection", "report", "gpu_history" ] }, "CloudGPUInventoryModel": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string" }, "gpu_count": { "type": "integer", "minimum": 0 }, "running_gpus": { "type": "integer", "minimum": 0 }, "stopped_gpus": { "type": "integer", "minimum": 0 }, "other_gpus": { "type": "integer", "minimum": 0 }, "vm_count": { "type": "integer", "minimum": 0 } }, "required": [ "model", "gpu_count", "running_gpus", "stopped_gpus", "other_gpus", "vm_count" ] }, "CloudGPUInventory": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_gpus": { "type": "integer", "minimum": 0 }, "running_gpus": { "type": "integer", "minimum": 0 }, "stopped_gpus": { "type": "integer", "minimum": 0 }, "other_gpus": { "type": "integer", "minimum": 0 }, "gpu_vms": { "type": "integer", "minimum": 0 }, "unknown_count_vms": { "type": "integer", "minimum": 0 }, "unknown_model_gpus": { "type": "integer", "minimum": 0 }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/CloudGPUInventoryModel" } } }, "required": [ "status", "observed_at", "total_gpus", "running_gpus", "stopped_gpus", "other_gpus", "gpu_vms", "unknown_count_vms", "unknown_model_gpus", "models" ], "description": "Known attached GPU counts grouped by model and VM power state. This is not device utilization, schedulable capacity, or workload attribution. Unknown GPU counts and models remain explicit. Source status and observation time identify retained or unavailable data." }, "CloudGPUHistory": { "type": "object", "additionalProperties": false, "properties": { "day": { "type": "string", "format": "date" }, "inventory": { "$ref": "#/components/schemas/CloudGPUInventory" } }, "required": [ "day", "inventory" ], "description": "Latest successfully collected inventory aggregate for one UTC day and the current connection revision. Does not include resource identifiers, names, tags, or customer commands. Missing days are absent rather than zero." }, "CloudExecutionHost": { "type": "object", "additionalProperties": false, "properties": { "host_id": { "type": "string", "description": "Nodus host identity in the dedicated pool." }, "resource_id": { "type": "string", "description": "Customer-owned AWS EC2 instance ID or Google Compute Engine numeric instance ID recorded by the administrator." }, "region": { "type": "string", "description": "Cloud region containing the observed instance." }, "bound_at": { "type": "string", "format": "date-time" }, "execution_configured": { "type": "boolean", "description": "The enrolled host has declared the required Nodus execution configuration. Health, cloud authorization and available capacity are checked separately. This is not a physical host attestation." }, "zone": { "type": "string", "description": "Google Compute Engine zone containing the instance. Omitted for AWS associations." } }, "required": [ "host_id", "resource_id", "region", "bound_at", "execution_configured" ], "description": "An administrator-declared association between an enrolled Nodus host and observed AWS or Google Cloud capacity. This association does not attest the physical instance identity or grant execution credentials." }, "CloudExecution": { "type": "object", "additionalProperties": false, "properties": { "connection_id": { "type": "string", "description": "Nodus cloud connection identity." }, "pool_id": { "type": "string", "description": "Dedicated Nodus pool identity, present after execution has first been enabled." }, "enabled": { "type": "boolean", "description": "Explicit authorization for future private workload routing. Host enrollment, health and available capacity are checked separately." }, "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/CloudExecutionHost" } } }, "required": [ "connection_id", "enabled", "hosts" ] }, "CloudExecutionUpdate": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "CloudExecutionHostInput": { "type": "object", "additionalProperties": false, "properties": { "host_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "resource_id": { "type": "string", "pattern": "^(?:i-(?:[a-f0-9]{8}|[a-f0-9]{17})|[1-9][0-9]{0,19})$", "description": "AWS EC2 instance ID or Google Compute Engine server-generated uint64 instance ID, supplied as a decimal string. IDs and regions must match the connection provider." }, "region": { "type": "string", "pattern": "^(?:[a-z]{2}(?:-[a-z]+)+-[0-9]+|[a-z]+(?:-[a-z]+)+[0-9]+)$" }, "zone": { "type": "string", "pattern": "^[a-z]+(?:-[a-z]+)+[0-9]+-[a-z]$", "description": "Required for Google Cloud and must belong to the supplied region. Omit for AWS." } }, "required": [ "host_id", "resource_id", "region" ] }, "GoogleCloudAuthorization": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "consent", "exchanging", "authorized", "connecting", "completed", "cancelled" ] }, "expires_at": { "type": "string", "format": "date-time" }, "session_id": { "type": "string" }, "step": { "type": "integer", "minimum": 0, "maximum": 7 }, "billing_status": { "type": "string", "enum": [ "not_requested", "preparing", "ready", "needs_setup" ] } }, "required": [ "id", "state", "expires_at", "step", "billing_status" ], "description": "Temporary setup authorization owned by the consenting team administrator. No Google tokens or private federation configuration are returned." }, "GoogleCloudProject": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "GoogleCloudAuthorizationResponse": { "type": "object", "additionalProperties": false, "properties": { "authorization": { "$ref": "#/components/schemas/GoogleCloudAuthorization" }, "authorization_url": { "type": "string", "format": "uri" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleCloudProject" } }, "next_page_token": { "type": "string" }, "message": { "type": "string" }, "session": { "$ref": "#/components/schemas/CloudOnboardingSession" }, "connection": { "$ref": "#/components/schemas/CloudObservationConnection" }, "next_action": { "$ref": "#/components/schemas/CloudOnboardingAction" } }, "required": [ "authorization" ] }, "ManagedBrokerLimits": { "type": "object", "additionalProperties": false, "description": "Immutable lifetime request, token, read-byte and invocation-history ceilings. At least one operation kind must have a positive request allowance. Model requests require positive input and output allowances. Zero model or tool requests require their matching unit allowances to be zero. Limits must fit an independently configured account policy. Waiting and unknown outcomes retain their counted liabilities. These units do not represent model prices.", "properties": { "model_requests": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "input_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "tool_requests": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "read_bytes": { "type": "integer", "minimum": 0, "maximum": 1099511627776 }, "max_concurrent": { "type": "integer", "minimum": 1, "maximum": 1024 }, "max_retained_invocations": { "type": "integer", "minimum": 1, "maximum": 100000 }, "max_retained_bytes": { "type": "integer", "minimum": 4096, "maximum": 1073741824 } }, "required": [ "model_requests", "input_tokens", "output_tokens", "tool_requests", "read_bytes", "max_concurrent", "max_retained_invocations", "max_retained_bytes" ] }, "ManagedBrokerModelUsage": { "type": "object", "additionalProperties": false, "description": "Active counts dispatched requests. Unresolved counts dispatched effects whose results remain unknown. Both retain concurrency and reserved units until authoritative settlement.", "properties": { "requests_used": { "type": "integer", "minimum": 0 }, "requests_reserved": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "unresolved": { "type": "integer", "minimum": 0 }, "input_tokens_used": { "type": "integer", "minimum": 0 }, "output_tokens_used": { "type": "integer", "minimum": 0 }, "input_tokens_reserved": { "type": "integer", "minimum": 0 }, "output_tokens_reserved": { "type": "integer", "minimum": 0 } }, "required": [ "requests_used", "requests_reserved", "active", "unresolved", "input_tokens_used", "output_tokens_used", "input_tokens_reserved", "output_tokens_reserved" ] }, "ManagedBrokerToolUsage": { "type": "object", "additionalProperties": false, "properties": { "requests_used": { "type": "integer", "minimum": 0 }, "requests_reserved": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "unresolved": { "type": "integer", "minimum": 0 }, "read_bytes_used": { "type": "integer", "minimum": 0 }, "read_bytes_reserved": { "type": "integer", "minimum": 0 } }, "required": [ "requests_used", "requests_reserved", "active", "unresolved", "read_bytes_used", "read_bytes_reserved" ] }, "ManagedBrokerWait": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "enum": [ "model_request_limit", "model_token_limit", "tool_request_limit", "tool_byte_limit", "broker_concurrency_limit", "broker_outcome_unknown", "broker_unavailable" ] }, "requests": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "reason", "requests" ] }, "ManagedBrokerUsage": { "type": "object", "additionalProperties": false, "properties": { "model": { "$ref": "#/components/schemas/ManagedBrokerModelUsage" }, "tools": { "$ref": "#/components/schemas/ManagedBrokerToolUsage" }, "waits": { "type": "array", "maxItems": 7, "items": { "$ref": "#/components/schemas/ManagedBrokerWait" } } }, "required": [ "model", "tools", "waits" ] }, "ManagedPeerUsage": { "type": "object", "additionalProperties": false, "description": "Lifetime accepted message counts and payload bytes. Received means committed to the recipient journal. It does not prove the application acted on a message. Uncertain publication ownership remains visible until independently reconciled.", "properties": { "messages": {"type": "integer", "minimum": 0}, "bytes": {"type": "integer", "minimum": 0}, "pending": {"type": "integer", "minimum": 0}, "received": {"type": "integer", "minimum": 0}, "undelivered": {"type": "integer", "minimum": 0}, "cleanup_pending": {"type": "integer", "minimum": 0}, "cleanup_unresolved": {"type": "integer", "minimum": 0}, "max_messages": {"type": "integer", "minimum": 1, "maximum": 10000}, "max_bytes": {"type": "integer", "minimum": 1, "maximum": 33554432} }, "required": ["messages", "bytes", "pending", "received", "undelivered", "cleanup_pending", "cleanup_unresolved", "max_messages", "max_bytes"] }, "ManagedAgentGroupCreate": { "type": "object", "additionalProperties": false, "properties": { "attempt_budget_usd": { "type": ["number", "null"], "minimum": 0.000001, "maximum": 1000000, "multipleOf": 0.000001, "description": "Optional fixed attempt reservation in whole microdollars. It can narrow the selected revision cap. Omission inherits that revision cap." }, "name": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "agent_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "revision": { "type": "integer", "minimum": 0, "description": "Omit or use zero to pin the current definition revision when the group is created." }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000, "multipleOf": 1e-06, "description": "Omit or use zero for account funding without a group spending limit. An explicit positive value is a compute sublimit of any positive deployment budget. Payment, available credits, deployment limits and accepted attempt limits still apply. This does not create a second funded balance." }, "max_active": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Authorized attempts in admitting, starting or running state, including retained waiting workers. This is not measured productive concurrency." }, "max_held": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Allocations awaiting confirmed physical cleanup, including provisioning, draining and uncertain resources. Pending accounting retains spending reservations after physical capacity is released. Must be at least max_active and at most the deployment worker limit." }, "max_pending": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "All nonterminal tasks, including active, waiting and blocked work. Omit or use zero for the smaller of 1000 and the account entitlement." }, "broker_limits": { "$ref": "#/components/schemas/ManagedBrokerLimits", "description": "Optional independently enabled broker enrollment. Omission preserves existing direct model and tool workflows. Accepted limits are immutable." } }, "required": [ "name", "agent_id", "max_active", "max_held" ] }, "ManagedAgentGroupTask": { "type": "object", "additionalProperties": false, "properties": { "task_key": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "description": "Immutable identity within this group. Reuse with identical content to recover the same run." }, "input": { "description": "Valid JSON without duplicate object keys, bounded to 256 KiB. The complete batch is also limited to 1 MiB." }, "depends_on": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "maxItems": 100, "uniqueItems": true, "description": "Prerequisite task keys from this group or the same batch. All prerequisites must commit success before dispatch. Results are not automatically copied into this input." }, "deadline": { "type": "string", "format": "date-time", "description": "A new task deadline must be in the future. Accepted task retries preserve the original deadline." } }, "required": [ "task_key", "input" ] }, "ManagedAgentGroupBatchRequest": { "type": "object", "additionalProperties": false, "properties": { "tasks": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ManagedAgentGroupTask" } } }, "required": [ "tasks" ] }, "ManagedAgentGroupTaskReceipt": { "type": "object", "additionalProperties": false, "properties": { "task_key": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "run_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" } }, "required": [ "task_key", "run_id" ] }, "ManagedAgentGroupBatch": { "type": "object", "additionalProperties": false, "properties": { "group_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "runs": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/ManagedAgentGroupTaskReceipt" }, "description": "Stable task and run identities in request order." } }, "required": [ "group_id", "runs" ] }, "ManagedAgentGroup": { "type": "object", "additionalProperties": false, "properties": { "attempt_budget_usd": { "type": ["number", "null"], "minimum": 0.000001, "maximum": 1000000, "multipleOf": 0.000001, "description": "Immutable fixed attempt reservation accepted for this group and its child runs. Absent for the legacy allocation policy." }, "id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "name": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "agent_id": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "active", "cancelled" ], "description": "Admission lifecycle. Use logical_runs for task progress and allocations for remaining cleanup." }, "budget_usd": { "type": "number", "minimum": 0, "maximum": 1000000, "multipleOf": 1e-06, "description": "Zero means account funding without a group spending limit. A positive value is the group's accepted compute sublimit of any positive deployment budget. Payment, available credits, deployment limits and accepted attempt limits still apply." }, "max_active": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Authorized attempts in admitting, starting or running state, including retained waiting workers. This is not measured productive concurrency." }, "max_held": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Allocations awaiting confirmed physical cleanup, including provisioning, draining and uncertain resources. Pending accounting retains spending reservations after physical capacity is released. Must be at least max_active and at most the deployment worker limit." }, "max_pending": { "type": "integer", "minimum": 1, "maximum": 10000 }, "max_retained_runs": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Persisted admission cap for runs whose payloads have not expired. Completion alone does not release this count." }, "created_at": { "type": "string", "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "logical_runs": { "$ref": "#/components/schemas/ManagedAgentLogicalRunCounts", "description": "Counts only tasks belonging to this group, excluding other groups and standalone runs. Running does not establish productive activity." }, "allocations": { "$ref": "#/components/schemas/ManagedAgentAllocationObservations", "description": "Retained attempts and resources assigned to this group. Unassigned warm attempts belong to the deployment account and are excluded. Counts can overlap and do not establish current healthy capacity." }, "retained_runs": { "type": "integer", "minimum": 0 }, "cost_usd": { "type": "number", "minimum": 0, "description": "Settled attempt costs and recorded compute charges for unsettled attempts without a spending cap, within the deployment account." }, "reserved_usd": { "type": "number", "minimum": 0, "description": "Full accepted budget liability of unsettled assigned attempts with a spending cap, plus outstanding account funding reservations for attempts without a cap. A closed marker alone cannot release these reservations." }, "active_authorized_attempts": { "type": "integer", "minimum": 0, "description": "Attempts in admitting, starting or running state. Includes retained waiting or recovering workers and does not establish productive activity." }, "work_status": { "type": "string", "enum": [ "empty", "pending", "running", "waiting", "blocked", "completed", "cancelled", "cancelling" ], "description": "Read-only summary of the current logical runs, independent of group admission and remaining cleanup." }, "blocked_reasons": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ManagedAgentGroupBlockedReason" }, "description": "Sorted public categories counting each waiting or blocked logical run once. Active running work is excluded unless group cancellation fences it. Empty groups return an empty array." }, "cleanup_status": { "type": "string", "enum": [ "complete", "pending", "unresolved" ], "description": "Separate from useful task completion. Unresolved resource, accounting or message publication evidence takes precedence, followed by pending allocation or inbox cleanup." }, "broker_limits": { "$ref": "#/components/schemas/ManagedBrokerLimits", "description": "Optional independently enabled broker enrollment. Omission preserves existing direct model and tool workflows. Accepted limits are immutable." }, "broker_usage": { "$ref": "#/components/schemas/ManagedBrokerUsage", "description": "Present only for broker-enrolled groups. Separate integer model and tool accounting from compute costs and logical-run wait counts." }, "peer_messaging": { "type": "boolean", "description": "Read-only availability of direct task messaging, assigned automatically when this group is admitted on a supported deployment. Existing groups retain their original availability." }, "peer_usage": { "$ref": "#/components/schemas/ManagedPeerUsage" } }, "required": [ "id", "name", "agent_id", "revision", "status", "budget_usd", "max_active", "max_held", "max_pending", "max_retained_runs", "created_at", "cancelled_at", "logical_runs", "allocations", "retained_runs", "cost_usd", "reserved_usd", "active_authorized_attempts", "work_status", "blocked_reasons", "cleanup_status" ] }, "ManagedAgentGroupBlockedReason": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "enum": [ "admission_rejected", "admission_retry", "allocation_cleanup", "attention_required", "budget", "cancelling", "children", "dependencies", "dependency_blocked", "execution_capacity", "external_outcome_unknown", "messages", "queued", "recovering", "session", "signal", "starting", "timer", "waiting", "workspace_capacity" ] }, "runs": { "type": "integer", "minimum": 1 } }, "required": [ "reason", "runs" ] }, "TrainingDistribution": { "type": "object", "additionalProperties": false, "required": [ "framework" ], "properties": { "mode": { "type": "string", "enum": [ "", "standard", "low_communication" ], "description": "Omission means standard training with the customer's declared algorithm unchanged." }, "framework": { "type": "string", "enum": [ "pytorch", "accelerate", "deepspeed", "jax", "tensorflow", "custom" ] }, "processes_per_node": { "type": "integer", "minimum": 0, "maximum": 64, "description": "Processes per machine. Positive for explicit node topology. Zero or omission is allowed only with total_gpu_count greater than one and is resolved before allocation." }, "geography": { "type": "string", "enum": [ "", "single_region", "cross_region" ], "description": "Omission permits a single region only. Data-location restrictions still apply." }, "config_file": { "type": "string", "maxLength": 1024, "description": "Relative project path to the Accelerate launcher configuration. Required for Accelerate and rejected for other launchers. Must match launch.config_file in nodus.training.json." }, "diloco": { "$ref": "#/components/schemas/DiLoCoProfile" } } }, "DiLoCoProfile": { "type": "object", "additionalProperties": false, "required": [ "version", "islands", "local_steps", "outer_learning_rate", "outer_momentum", "synchronization_timeout_seconds" ], "properties": { "version": { "type": "integer", "const": 1 }, "islands": { "type": "integer", "minimum": 2, "maximum": 256 }, "local_steps": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "outer_learning_rate": { "type": "number", "exclusiveMinimum": 0 }, "outer_momentum": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "synchronization_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 3600 } }, "description": "Explicit fixed-membership DiLoCo configuration. Requires low_communication mode and the PyTorch launcher. This configuration does not establish a qualified training profile." }, "DistributedObservedProgress": { "type": "object", "properties": { "completed_units": { "type": "integer" }, "total_units": { "type": "integer" }, "last_loss": { "type": "number" }, "metric_rate": { "type": "number" }, "metric_step": { "type": "integer" }, "metric_total_steps": { "type": "integer" }, "metric_epoch": { "type": "number" }, "metric_total_epochs": { "type": "number" }, "observed_at": { "type": "string", "format": "date-time" } }, "required": [ "completed_units", "total_units", "observed_at" ], "description": "Member observations for display. These values are not a saved recovery point and must not be summed across tensor or pipeline ranks." }, "DistributedCustomerMember": { "type": "object", "properties": { "member_id": { "type": "string" }, "node_rank": { "type": "integer" }, "ready": { "type": "boolean" }, "started": { "type": "boolean" }, "active": { "type": "boolean" }, "exit_code": { "type": "integer" }, "observed_progress": { "$ref": "#/components/schemas/DistributedObservedProgress" } }, "required": [ "member_id", "node_rank", "ready", "started", "active" ] }, "DistributedCustomerGroup": { "type": "object", "properties": { "group_id": { "type": "string" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "phase": { "type": "string", "enum": [ "assembling", "prepared", "starting", "running", "stopping", "closed" ] }, "outcome": { "type": "string", "enum": [ "completed", "failed", "cancelled" ] }, "cleanup_state": { "type": "string", "enum": [ "pending", "complete" ] }, "required_members": { "type": "integer" }, "ready_members": { "type": "integer" }, "active_members": { "type": "integer" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/DistributedCustomerMember" } } }, "required": [ "group_id", "stage_id", "generation", "phase", "cleanup_state", "required_members", "ready_members", "active_members", "members" ], "description": "Latest distributed attempt for a workload stage. Ready counts record completed preparation. Active counts require started work with unexpired execution authority. Outcome and resource cleanup are separate." }, "DistributedLogChunk": { "type": "object", "properties": { "group_id": { "type": "string" }, "member_id": { "type": "string" }, "node_rank": { "type": "integer" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "offset": { "type": "integer" }, "text": { "type": "string" }, "data_base64": { "type": "string", "contentEncoding": "base64", "description": "Exact customer program bytes. Text provides a UTF-8 display representation." } }, "required": [ "group_id", "member_id", "node_rank", "stage_id", "generation", "offset", "text", "data_base64" ] } }, "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Nodus API key" } } }, "externalDocs": { "url": "https://github.com/nodus-compute/Nodus-sdk-python/tree/main/docs" }, "info": { "title": "Nodus Infrastructure Execution API", "version": "1.1.0", "description": "Provider-neutral infrastructure execution for AI workloads. This contract describes customer API-key workload, sandbox, managed model, research workspace, asset, webhook, and cloud observation operations. Console sign-in, operator, runner, and supplier protocols are outside its scope. Obtain a key using nodus login or the console. Use the deployment API origin as the base URL. No paid workload is executed by viewing this contract." }, "openapi": "3.1.0", "paths": { "/v1/assets": { "get": { "operationId": "listAssets", "summary": "List imported code and datasets", "tags": [ "Assets" ], "description": "Returns the latest 500 nondeleted assets, newest first. Generated workspace_source aliases expose current removability and shared-source references. workspace_source_storage reports their separate included account pool. Ordinary import limits and quota do not include these generated copies. Deleting an alias releases source storage only after the final reference is removed and exact cleanup is confirmed. Limits describe this deployment and may change.", "responses": { "200": { "description": "Asset list and storage limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" } } } }, "500": { "description": "Asset listing or storage usage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/assets/import": { "post": { "operationId": "importAsset", "summary": "Import code or a dataset", "tags": [ "Assets" ], "description": "Import a GitHub repository, a Hugging Face dataset repository, or a public HTTPS file or archive. GitHub imports can use the team's connected GitHub account. URL imports use signed links for private downloads and reject tokens. GitHub, Hugging Face and URL imports may take up to ten minutes. It has no idempotency contract. After a timeout, inspect the asset list before repeating the request. Database connection queries return 202 after durable admission and export to Parquet or CSV in bounded workers. Poll the returned asset until ready or failed. Execution including queue time is bounded to ten minutes. reuse may return a ready export from the last 24 hours. New requests otherwise create fresh assets. Failed exports expose a safe error and retain their storage reservation until object cleanup succeeds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetImportRequest" } } } }, "responses": { "201": { "description": "Import complete and asset ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "description": "Invalid import, source access, unsupported archive or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Storage quota reached or two imports already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Asset staging or commit failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Object storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Eligible query export reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "202": { "description": "Database query admitted. Poll GET /v1/assets/{id} until ready or failed. Disconnecting does not cancel admitted work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } } } } }, "/v1/assets/upload": { "post": { "operationId": "uploadAsset", "summary": "Upload a local file or archive", "tags": [ "Assets" ], "description": "Send raw file bytes, not multipart form data. The server packages a file or extracts a supported archive. Read max_import_bytes and upload_idempotency from GET /v1/assets first. When upload_idempotency is true, send a stable Idempotency-Key and X-Nodus-SHA256 for verified replay of the same bytes and name. An in-progress, failed or deleted keyed upload returns an actionable conflict without creating a replacement. Unkeyed uploads retain their existing behavior. After an uncertain unkeyed response, inspect the asset list before repeating the request.", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "default": "dataset" }, "description": "Filename, including its archive extension when uploading an archive." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!-~]+$" }, "description": "Optional stable upload identity. Requires X-Nodus-SHA256. Replaying identical bytes and name returns the same ready asset." }, { "name": "X-Nodus-SHA256", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "SHA-256 of the exact request bytes. Required with Idempotency-Key. Different bytes or name cannot reuse an upload key." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Upload complete and asset ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "description": "Invalid file, archive or size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Storage quota reached or two imports already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Asset staging or commit failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Object storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/assets/{id}": { "get": { "operationId": "getAsset", "summary": "Read an asset owned by the authenticated team", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Asset identifier returned by an import, upload or list." } ], "responses": { "200": { "description": "Asset metadata. This endpoint does not download file contents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "404": { "description": "Asset not found in the authenticated team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, rate limits and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAsset", "summary": "Delete an unused asset", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Asset identifier returned by an import, upload or list." } ], "responses": { "204": { "description": "Asset deleted" }, "404": { "description": "Asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Asset is importing or used by an active workload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Asset deletion could not be finalized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Stored input could not be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/benchmarks": { "post": { "operationId": "submitBenchmark", "summary": "Run a bounded workload matrix", "description": "Fans out ordinary workloads atomically with a single idempotency key. Each command can contain {{batch_size}}. Regions narrow workload data residency. Framework and multi-stage payloads are refused. GPU families use standard model names, never supplier SKUs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "202": { "description": "Benchmark accepted or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkReport" } } } }, "400": { "description": "Invalid matrix or workload" }, "402": { "description": "Payment or credits required" }, "409": { "description": "Idempotency conflict" }, "503": { "description": "Admission unavailable" } } } }, "/v1/benchmarks/{id}": { "get": { "operationId": "getBenchmark", "summary": "Read a benchmark report", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-cell observed costs, timings and workload links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchmarkReport" } } } }, "404": { "description": "Benchmark not found" } } } }, "/v1/me": { "get": { "summary": "Verify the current login", "operationId": "identity", "responses": { "200": { "description": "Authenticated identity. Email may be empty for a team key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "tenant": { "type": "string" }, "key_id": { "type": "string" } } } } } }, "401": { "description": "Credentials are invalid, expired, or revoked" } } } }, "/v1/sandboxes": { "post": { "operationId": "createSandbox", "summary": "Create a sandbox", "tags": [ "Sandboxes" ], "description": "Creates a durable execution environment after Nodus matches infrastructure and authorizes customer-funded usage. 202 means accepted and can precede readiness. Payment and credits are checked before billable placement.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCreateRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } }, "headers": { "Idempotent-Replayed": { "description": "true when the response replays the original operation.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } }, "get": { "operationId": "listSandboxes", "summary": "List sandboxes", "tags": [ "Sandboxes" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned by the previous page." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Exact customer label filter." }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/SandboxState" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "sandboxes", "next_cursor" ], "properties": { "sandboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Sandbox" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}": { "get": { "operationId": "getSandbox", "summary": "Get a sandbox", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/agent-events": { "post": { "operationId": "submitAgentEvent", "summary": "Commit an event and wake its sandbox driver", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEventRequest" } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEvent" } } } }, "default": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Account authentication is required. Receipt, immutable run, driver exec and normal lifecycle wake intent commit atomically. Exact source and event ID replay returns the same logical run. Changed command or payload conflicts. Normal billing, deadline, capacity and cleanup gates still apply. Queued events expire after seven days. Lost drivers have at most three attempts and unknown external effects block automatic restart." } }, "/v1/sandboxes/{id}/agent-events/{event_id}": { "get": { "operationId": "getAgentEvent", "summary": "Read event handling state", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } }, { "name": "source", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEvent" } } } }, "default": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Handled means the logical run durably completed. Dispatch and queue acknowledgement do not imply successful handling." } }, "/v1/sandboxes/{id}/agent-runs": { "post": { "operationId": "createAgentRun", "summary": "Register immutable durable agent input", "description": "Requires an enabled durable-agent deployment. Repeating an identical run ID replays registration. Changed input, name, version or image conflicts. Registration does not start compute.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunRequest" } } } } } }, "/v1/sandboxes/{id}/agent-runs/{run_id}": { "get": { "operationId": "getAgentRun", "summary": "Read a durable agent run", "description": "Payloads expire 30 days after the run or sandbox becomes terminal. Expired tombstones never authorize execution.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } }, "delete": { "operationId": "deleteAgentRun", "summary": "Erase journal payloads and fence the run permanently", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "default": { "description": "Request refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Retains an expired tombstone and digests. An identical run ID cannot authorize another execution. Cancels its queued event driver and requests cancellation of a running event driver." } }, "/v1/sandboxes/{id}/agent-runs/{run_id}/resolve": { "post": { "operationId": "resolveAgentStep", "summary": "Resolve an independently verified unknown effect", "description": "Compare-and-swap requires the current unknown step revision and an evidence digest. completed requires the verified JSON result. no_effect authorizes one further bounded attempt. cancelled stops the run. Original unknown attempts remain retained.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReceipt" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResolution" } } } } } }, "/v1/sandboxes/{id}/agent-runs/{run_id}/steps": { "get": { "operationId": "listAgentSteps", "summary": "Read a page of durable step metadata", "description": "Unknown external effects block the run until explicitly resolved using independent evidence.", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } }, { "name": "after", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStepPage" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/events": { "get": { "operationId": "listSandboxEvents", "summary": "Read sandbox lifecycle and network denial events", "tags": [ "Sandboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WorkloadEvent" } } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Exclusive numeric event ID cursor. At most 100 events per response." }, { "name": "latest", "in": "query", "schema": { "type": "boolean" }, "description": "Return the most recent 100 events in descending order. Cannot be combined with a nonzero after cursor." } ], "description": "Returns up to 100 retained events in ascending ID order. Poll with after set to the last received event ID. Network denial events contain only the denied hostname, count and generation." } }, "/v1/sandboxes/{id}/exec": { "post": { "operationId": "createSandboxExec", "summary": "Execute a command", "tags": [ "Sandboxes" ], "description": "Queues one process inside the sandbox. The sandbox can execute multiple commands over its lifetime.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExecRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExec" } } }, "headers": { "Idempotent-Replayed": { "description": "true when the response replays the original operation.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/execs/{exec_id}": { "get": { "operationId": "getSandboxExec", "summary": "Get command state", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exec_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When true, wait up to 30 seconds for the state to change or become terminal." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExec" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/execs/{exec_id}/cancel": { "post": { "operationId": "cancelSandboxExec", "summary": "Request command cancellation", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exec_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExec" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/execs/{exec_id}/resize": { "post": { "operationId": "resizeSandboxExec", "summary": "Set terminal dimensions", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exec_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxTerminalSize" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxTerminalSizeReceipt" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/execs/{exec_id}/stdin": { "post": { "operationId": "writeSandboxExecStdin", "summary": "Write command input", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exec_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxStdinRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxStdinReceipt" } } }, "headers": { "Idempotent-Replayed": { "description": "true when the response replays the original operation.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/execs/{exec_id}/stream": { "get": { "operationId": "readSandboxExecOutput", "summary": "Read command output", "tags": [ "Sandboxes" ], "description": "Reads ordered stdout and stderr frames after a sequence cursor. Repeat with next_sequence to stream without losing output.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exec_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 16, "default": 16 } }, { "name": "wait", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When true, wait up to 30 seconds for output or terminal state." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxOutputPage" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/metrics": { "get": { "operationId": "getSandboxMetrics", "summary": "Read sandbox measurements and 24 hour resource history", "tags": [ "Sandboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMetricReport" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Samples arrive approximately every 30 seconds while authorized runtime authority is active. Raw samples are retained for 7 days. Latest is the newest retained sample and can be stale, so inspect observed_at. History covers the last 24 hours. Resource measurements never create billing authority." } }, "/v1/sandboxes/{id}/ports/{port}/{path}": { "get": { "operationId": "getSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "head": { "operationId": "headSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "post": { "operationId": "postSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } } } }, "put": { "operationId": "putSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } } } }, "patch": { "operationId": "patchSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } } } }, "delete": { "operationId": "deleteSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } } } }, "options": { "operationId": "optionsSandboxHTTP", "tags": [ "Sandboxes" ], "summary": "Send an authenticated HTTP request to a guest application", "description": "Request and response bodies are limited to 64 KiB. Authorization and Cookie headers are not forwarded. Requests time out after 15 seconds and are never automatically replayed. A timed out mutation may have executed. Use application idempotency keys. HTML responses have an isolated sandbox origin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Guest HTTP response or a bounded relay error. Guest cookies and redirects are not forwarded.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 65536 } } } } } }, "/v1/sandboxes/{id}/refresh-secrets": { "post": { "operationId": "refreshSandboxSecrets", "summary": "Refresh sandbox secret bindings", "tags": [ "Secrets" ], "responses": { "204": { "description": "Success" }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Binds current versions for subsequent commands. Already running processes keep their environment. Output redaction covers both current and previously bound versions. Possible split-frame fragments at frame edges are conservatively redacted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/sandboxes/{id}/terminate": { "post": { "operationId": "terminateSandbox", "summary": "Terminate a sandbox", "tags": [ "Sandboxes" ], "description": "Stops future execution and schedules exact cleanup of sandbox resources.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } }, "headers": { "Idempotent-Replayed": { "description": "true when the response replays the original operation.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "202": { "description": "Workspace final save requested. Poll the sandbox until termination completes. Saving failures preserve the last useful archive and appear in workspace metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } } } } } }, "/v1/secrets": { "post": { "operationId": "putSecret", "summary": "Write a secret version", "tags": [ "Secrets" ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretMetadata" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Creates a new encrypted version. Admitted sandboxes retain their pinned versions. Retired ciphertext is destroyed after seven days only when no nonterminal sandbox or connection retains it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretWrite" } } } } }, "get": { "operationId": "listSecrets", "summary": "List secret names and versions", "tags": [ "Secrets" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretMetadata" } } } } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Returns current metadata only. Secret values are never returned by customer read routes." } }, "/v1/secrets/{name}": { "delete": { "operationId": "deleteSecret", "summary": "Retire a secret", "tags": [ "Secrets" ], "responses": { "204": { "description": "Success" }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Removes the name from future bindings. Existing sandbox bindings continue until refresh or expiration.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhooks": { "get": { "operationId": "getWebhook", "summary": "Read the account webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "404 if not configured. Secret is never returned by GET." }, "put": { "operationId": "putWebhook", "summary": "Create or replace the account webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "secret": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string" } }, "required": [ "url" ] } } } }, "description": "One webhook per account. Use public HTTPS. Omitted secret generates one. Save the PUT response securely." }, "delete": { "operationId": "deleteWebhook", "summary": "Delete the account webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workloads": { "post": { "operationId": "createWorkload", "summary": "Submit a workload", "tags": [ "Workloads" ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } }, "headers": { "Idempotent-Replayed": { "description": "true on a replay of the original submission.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required stable key per logical submission. Replay the same payload with the same key. Different payload returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkloadPayload" } } } }, "description": "202 means accepted, not running. 402 payment_method_required means an administrator must add a payment method in console Billing before running workloads, including runs using starter credits. 402 credits_exhausted means the available credits cannot fund submission. 409 is an idempotency conflict. 503 spend_check_unavailable may be retried using the same key." }, "get": { "operationId": "listWorkloads", "summary": "List workloads", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workloads": { "type": "array", "items": { "$ref": "#/components/schemas/WorkloadListItem" } }, "next_offset": { "type": "integer" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size. 1–100. Omitted, nonpositive, or over 100 defaults to 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Offset returned by the previous page. Omitted starts at zero." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated statuses. Active and terminal expand to lifecycle groups. Unknown tokens are ignored." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mine", "team" ], "default": "team" }, "description": "Team lists all workloads in your team. Mine lists workloads attributed to the authenticated member before pagination. Mine requires a member-associated credential and returns attribution_required otherwise. Historical workloads and shared keys can have no owner. This filter does not change shared team access." } ] } }, "/v1/workloads/{id}": { "get": { "operationId": "getWorkload", "summary": "Get workload status, stages, route and meter", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workload" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ] } }, "/v1/workloads/{id}/artifacts": { "get": { "operationId": "listWorkloadArtifacts", "summary": "List checkpoint manifest metadata", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Artifact" } } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ] } }, "/v1/workloads/{id}/cancel": { "post": { "operationId": "cancelWorkload", "summary": "Request cancellation", "tags": [ "Workloads" ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Returns cancel_requested. Cancellation stops the workload and schedules resource cleanup. A cancelled status does not confirm that instance termination has finished. Calling after completion is safe and does not change the terminal result." } }, "/v1/workloads/{id}/events": { "get": { "operationId": "listWorkloadEvents", "summary": "Read lifecycle events", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WorkloadEvent" } } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclusive numeric event ID cursor. At most 100 events per response." } ] } }, "/v1/workloads/{id}/ledger": { "get": { "operationId": "getWorkloadLedger", "summary": "Get posted ledger and settlement", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workload_id": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLedgerEntry" } }, "settlement": { "$ref": "#/components/schemas/Settlement" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Settlement balance_usd is the accounting balance, not the total charge. Derive charges from customer_charge ledger entry credits. Meter.total_now_usd includes current accrual." } }, "/v1/workloads/{id}/logs": { "get": { "operationId": "getWorkloadLogs", "summary": "Read the latest committed stdout/stderr snapshot", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Nodus-SHA256": { "schema": { "type": "string" }, "description": "SHA-256 of stored bytes, when available." }, "X-Nodus-Log-Source": { "schema": { "type": "string", "enum": [ "live-snapshot" ] }, "description": "Present when the response uses retained live output instead of a committed artifact." }, "X-Nodus-Log-Truncated": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "For a live snapshot, whether capture or response limits truncated the retained output. Cancellation can also omit output not received before termination." }, "X-Nodus-Group-Id": { "schema": { "type": "string" }, "description": "Nodus group identifier for distributed snapshots." }, "X-Nodus-Member-Id": { "schema": { "type": "string" }, "description": "Nodus member identifier for distributed snapshots." }, "X-Nodus-Log-Expired": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether the distributed snapshot has passed its retention deadline." } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "description": "stage" }, { "name": "generation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Positive generation. Omit for the latest matching recorded log." }, { "name": "member_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nodus distributed member identifier from workload detail. Required when selecting distributed logs." } ], "description": "Returns a committed log artifact when available. If no artifact matches, returns the latest matching retained live snapshot within 24 hours after termination, limited to 8 MiB per attempt. This is a snapshot, not a live stream. Returns 404 when neither exists. X-Nodus-Stage-Id and X-Nodus-Generation identify the returned attempt. A member_id selects the retained distributed member snapshot and honors stage and generation filters. Distributed logs remain available during cleanup and expire 24 hours after workload termination once the group is closed." } }, "/v1/workloads/{id}/logs/live": { "get": { "summary": "Read live program log chunks", "operationId": "liveLogs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from the previous response." }, { "name": "member_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nodus distributed member identifier from workload detail. Required when selecting distributed logs." } ], "responses": { "200": { "description": "Live logs, retained for 24 hours after termination. Capture is bounded to 8 MiB per generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveLogPage" } } } }, "404": { "description": "Workload not found" } }, "description": "Distributed member logs use a cursor bound to their group and member. Each response is byte-bounded. Expired closed groups return an empty page with truncated and expired set. Active groups retain logs during cleanup. The group shares an 8 MiB live log allowance." } }, "/v1/workloads/{id}/outputs": { "get": { "operationId": "listWorkloadOutputs", "summary": "List downloadable outputs", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workload_id": { "type": "string" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/Output" } } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Outputs from completed stages, excluding reserved runner names. Follow the stage-qualified download path using the same authenticated API origin." } }, "/v1/workloads/{id}/outputs/{name}": { "get": { "operationId": "downloadWorkloadOutput", "summary": "Download a named output", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Nodus-SHA256": { "schema": { "type": "string" }, "description": "SHA-256 of stored bytes, when available." } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "name" }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required to disambiguate duplicate output names across stages. Otherwise 409 ambiguous_output." }, { "name": "member_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nodus member from the verified output listing. Required for same-named distributed shards. Otherwise 409 ambiguous_output." } ], "description": "404 when absent. 410 when a legacy local-only artifact cannot be retrieved. Verify X-Nodus-SHA256 when present." } }, "/v1/workloads/{id}/routing": { "get": { "operationId": "getWorkloadRouting", "summary": "Inspect placement history", "tags": [ "Workloads" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workload_id": { "type": "string" }, "placements": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPlacement" } } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Ordered by stage ID and then generation. Nodus catalog identifiers and resource facts only." } }, "/v1/research-workspaces/storage": { "get": { "operationId": "getResearchWorkspaceAccountStorage", "summary": "Read the shared account saved-file allowance and charges", "tags": [ "Research workspaces" ], "description": "Requires account authentication. Reports combined saved-file usage and the account storage policy, independent of compute-session charges.", "responses": { "200": { "description": "Account saved-file usage and billing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceAccountStorage" } } } }, "default": { "description": "Authentication, rate limits and temporary storage failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/research-workspaces/{id}/files/export": { "post": { "operationId": "createResearchWorkspaceFileExport", "summary": "Prepare a pinned export of stopped saved files", "tags": [ "Research workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Requires stopped compute, no active transfer and the observed current revision. Repeating the same live revision reuses its fixed 24-hour export. Does not start compute or require credits. Concatenate segments in manifest order and verify their hashes and the complete archive before publishing the local file. Saved files use version 3 storage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceFileRevision" } } } }, "responses": { "200": { "description": "First page of a pinned saved-file export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceFileExport" } } } }, "default": { "description": "404 for an unavailable owned workspace or export, 409 for stale revision, active compute, pending transfer, empty files or legacy format, 410 for expired export, 429 for too many retained export revisions, and 503 for temporary storage failures. Authentication and rate limits apply. No credit balance is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/research-workspaces/{id}/files/exports/{export}": { "get": { "operationId": "getResearchWorkspaceFileExport", "summary": "Read an export page and refresh signed download URLs", "tags": [ "Research workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "export", "in": "path", "required": true, "schema": { "type": "string" }, "description": "export" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100160 }, "description": "Segment index from next_offset, zero when omitted." } ], "description": "Each page has at most 256 segment URLs. Existing exports remain readable after current saved files are deleted or compute resumes, until the fixed export expiry. This does not extend that expiry.", "responses": { "200": { "description": "Pinned export page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceFileExport" } } } }, "default": { "description": "404 for an unavailable owned workspace or export, 409 for stale revision, active compute, pending transfer, empty files or legacy format, 410 for expired export, 429 for too many retained export revisions, and 503 for temporary storage failures. Authentication and rate limits apply. No credit balance is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/research-workspaces/{id}/files/exports/{export}/segments/{segment}": { "get": { "operationId": "downloadResearchWorkspaceFileSegment", "summary": "Stream one pinned saved-file segment through the authenticated API", "tags": [ "Research workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "export", "in": "path", "required": true, "schema": { "type": "string" }, "description": "export" }, { "name": "segment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "segment" } ], "description": "Requires account authentication and a live owned export. Streams at most 64 MiB, with a 50-second server deadline. Verify Content-Length and X-Nodus-SHA256 against the manifest. A disconnected stream is incomplete and must be downloaded again.", "responses": { "200": { "description": "Exact saved-file segment", "headers": { "Content-Length": { "schema": { "type": "integer", "maximum": 67108864 } }, "X-Nodus-SHA256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "404 for an unavailable owned workspace or export, 409 for stale revision, active compute, pending transfer, empty files or legacy format, 410 for expired export, 429 for too many retained export revisions, and 503 for temporary storage failures. Authentication and rate limits apply. No credit balance is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/research-workspaces/{id}/files": { "delete": { "operationId": "deleteResearchWorkspaceFiles", "summary": "Delete the observed stopped saved-file revision", "tags": [ "Research workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" } ], "description": "Requires stopped compute, no active transfer and an unchanged observed revision. Removes current saved files while preserving workspace configuration. Existing export pins expire separately. Available independently of compute admission and credit balance. Refresh after an uncertain response before choosing a new deletion intent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceFileRevision" } } } }, "responses": { "200": { "description": "Saved files deleted and revision advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchWorkspaceFileDeletion" } } } }, "default": { "description": "404 for an unavailable owned workspace or export, 409 for stale revision, active compute, pending transfer, empty files or legacy format, 410 for expired export, 429 for too many retained export revisions, and 503 for temporary storage failures. Authentication and rate limits apply. No credit balance is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/research-workspaces/capabilities": { "get": { "operationId": "getResearchWorkspaceCapabilities", "summary": "Read workspace environment and storage limits", "tags": ["Research workspaces"], "description": "Requires a Bearer API key or console session. Reports deployment configuration and accepted request counts, not qualified GPU inventory, live capacity or a price quote.", "responses": { "200": { "description": "Workspace configuration capabilities", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceCapabilities"}} } }, "default": { "description": "Authentication, rate limits and transient failures apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/compute": { "get": { "operationId": "listCompute", "summary": "List instances and training launched by this account", "tags": ["Compute"], "description": "Requires a Bearer API key or console session. Returns standalone instances and training workloads newest first. Training that shares a sweep_id is one item whose id is sweep_ followed by the sweep id, with a group summary. Paused training holds no compute and lists under history, not in summary.running.training. A sweep is attributed to the launcher of its first submitted run, for both launched_by and the launched_by filter. Running saved workspaces appear in summary.running.workspace and become items only with include=workspaces or type=workspace. Contains no cost or price fields. Rows without recorded attribution report launched_by.client api.", "parameters": [ {"name": "state", "in": "query", "schema": {"type": "string", "enum": ["running", "history"], "default": "running"}}, {"name": "type", "in": "query", "schema": {"type": "string", "enum": ["instance", "training", "workspace"]}, "description": "workspace selects running saved workspaces and returns no history."}, {"name": "include", "in": "query", "schema": {"type": "string", "enum": ["workspaces"]}, "description": "Adds running saved workspaces as items of type workspace."}, {"name": "launched_by", "in": "query", "schema": {"type": "string", "enum": ["me", "agents"]}, "description": "agents selects claude-code, codex, cursor and mcp. me requires a credential associated with a team member."}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}, "description": "Opaque next_cursor from the previous page with the same filters."}, {"name": "Nodus-Client", "in": "header", "schema": {"type": "string"}, "description": "Launch attribution recorded on creation requests: python-sdk, cli, mcp, claude-code, codex or cursor. console is accepted only from console sessions. Other values are recorded as api."} ], "responses": { "200": {"description": "Compute page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ComputeList"}}}}, "default": {"description": "Authentication, rate limits and transient failures apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/v1/compute/groups/{id}": { "get": { "operationId": "getComputeGroup", "summary": "Read one training sweep and its runs", "tags": ["Compute"], "description": "Requires a Bearer API key or console session. The id is a sweep item id from GET /v1/compute. Group counts cover every member. Items are paged newest first. Returns 404 when the sweep has no training in the caller's account. Contains no cost or price fields.", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^sweep_.+"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}}], "responses": { "200": {"description": "Sweep group", "content": {"application/json": {"schema": {"type": "object", "required": ["group", "items", "next_cursor"], "properties": {"group": {"$ref": "#/components/schemas/ComputeGroup"}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/ComputeItem"}}, "next_cursor": {"type": ["string", "null"]}}}}}}, "default": {"description": "Authentication, rate limits and transient failures apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/v1/ssh-keys": { "get": { "operationId": "listSSHKeys", "summary": "List the caller's saved SSH public keys", "tags": ["SSH keys"], "description": "Requires a console session or an API key created by a team member. Returns that member's saved keys, the same list as the console Settings page. Every machine run by each of the member's teams admits these keys, including machines already running.", "responses": { "200": {"description": "Saved keys", "content": {"application/json": {"schema": {"type": "object", "required": ["keys"], "properties": {"keys": {"type": "array", "items": {"$ref": "#/components/schemas/SSHKey"}}}}}}}, "default": {"description": "400 invalid_ssh_key, 403 attribution_required for an API key without a creating team member, 409 ssh_key_limit. Authentication, rate limits and transient failures also apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } }, "post": { "operationId": "addSSHKey", "summary": "Save an SSH public key to the caller's account", "tags": ["SSH keys"], "description": "Requires a console session or an API key created by a team member. Accepts one plain Ed25519, RSA, ECDSA or OpenSSH security-key public key. An account holds up to 20 keys. Saving an existing key updates its name.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["public_key"], "properties": {"public_key": {"type": "string", "maxLength": 8192}, "name": {"type": "string", "maxLength": 100}}}}}}, "responses": { "201": {"description": "Key saved", "content": {"application/json": {"schema": {"type": "object", "required": ["fingerprint"], "properties": {"fingerprint": {"type": "string"}}}}}}, "default": {"description": "400 invalid_ssh_key, 403 attribution_required for an API key without a creating team member, 409 ssh_key_limit. Authentication, rate limits and transient failures also apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/v1/ssh-keys/{fingerprint}": { "delete": { "operationId": "removeSSHKey", "summary": "Remove a saved SSH public key", "tags": ["SSH keys"], "description": "Requires a console session or an API key created by a team member. Running machines stop admitting the key within seconds. Returns 404 when the caller's account has no such key.", "parameters": [{"name": "fingerprint", "in": "path", "required": true, "schema": {"type": "string"}, "description": "SHA256 fingerprint as returned when the key was saved."}], "responses": { "204": {"description": "Key removed"}, "default": {"description": "400 invalid_ssh_key, 403 attribution_required for an API key without a creating team member, 409 ssh_key_limit. Authentication, rate limits and transient failures also apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/v1/research-workspaces": { "post": { "operationId": "createResearchWorkspace", "summary": "Create a workspace or standalone instance configuration", "tags": ["Research workspaces"], "description": "Saves a unique named configuration without starting compute. Omitted kind creates a saved workspace. kind instance creates standalone SSH compute with local disk only and requires capabilities.standalone_instances. Requires a Bearer API key or console session. Workspace duplicate names are rejected. An instance retry with the exact same account, name and configuration returns the existing record. Different configurations still conflict. Use start to admit a compute session.", "requestBody": { "required": true, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceConfiguration"}} } }, "responses": { "201": { "description": "Saved workspace created, with compute stopped", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}} } }, "default": { "description": "400 for invalid configuration, duplicate name or exceeded storage limits. 503 workspace_unavailable when disabled. Authentication, quotas, rate limits and transient failures also apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } }, "get": { "operationId": "listResearchWorkspaces", "summary": "List saved research workspaces", "tags": ["Research workspaces"], "description": "Returns a page owned by the authenticated account, newest first. The default kind workspace excludes standalone instances. Use kind instance for standalone instances. Cursors are bound to the selected kind. The default and maximum page size are 100. Includes compute-session costs, separate retained-storage costs and tool readiness. Continue with next_cursor until it is empty. Pages reflect current records and do not form a snapshot across concurrent changes.", "parameters": [ {"name": "kind", "in": "query", "schema": {"type": "string", "enum": ["workspace", "instance"], "default": "workspace"}, "description": "Select saved workspaces or standalone instances without duplicate rows."}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 100}, "description": "Maximum workspaces on this page."}, {"name": "cursor", "in": "query", "schema": {"type": "string", "maxLength": 1024}, "description": "Opaque next_cursor from this account's previous research workspace page."} ], "responses": { "200": { "description": "Workspace list", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceList"}} } }, "default": { "description": "Authentication, rate limits and transient failures apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/research-workspaces/quote": { "post": { "operationId": "quoteWorkspacePrice", "summary": "Preview the whole-machine hourly price", "tags": ["Research workspaces"], "description": "Read-only estimate for the supplied configuration, including CPU or GPU requirements and runtime storage. Send the same configuration used for workspace creation. For a saved workspace, include workspace_id to account for the additional disk needed to restore its files. A successful estimate does not reserve capacity, lock the price or start compute. Refresh expired estimates before starting. Launch checks price, capacity and account funding again.", "parameters": [{"name": "workspace_id", "in": "query", "schema": {"type": "string"}, "description": "Optional saved workspace owned by this account. The supplied configuration must match its current saved revision. Includes restore disk in direct-compute estimates. Returns 404 for an unavailable workspace or 409 for a changed configuration."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceConfiguration"}}}}, "responses": { "200": {"description": "Current exact-configuration estimate", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkspacePricePreview"}}}}, "503": {"description": "quote_unavailable when a current eligible price cannot be confirmed. No compute is allocated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}}}}, "default": {"description": "400 for invalid configuration. Authentication, rate limits and transient failures apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}}}} } } }, "/v1/research-workspaces/{id}": { "delete": { "operationId": "deleteResearchWorkspace", "summary": "Delete a stopped workspace and its saved files", "tags": [ "Research workspaces" ], "description": "Requires stopped or failed compute with confirmed release and no pending file upload. Cancels a pending schedule, stops storage billing for the current saved files and releases the name and team workspace slot. Past sessions, charges and admitted workloads remain. Files pinned by an existing export or workload remain until their ownership ends. Reuse the same Idempotency-Key after an uncertain response.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved workspace identifier." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Stable retry key for this exact deletion." } ], "responses": { "200": { "description": "Workspace deleted or original deletion replayed", "headers": { "Idempotent-Replayed": { "description": "true when this is the saved response for the same retry key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "deleted", "deleted_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "deleted_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Workspace is unknown, belongs to another team or was deleted with a different retry key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "workspace_active requires compute to stop and saving to finish. workspace_transfer_pending requires the pending upload to finish or be discarded. idempotency_conflict requires the original request and key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, rate limits, invalid retry keys and transient errors apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateResearchWorkspaceConfiguration", "summary": "Change settings for the next workspace session", "tags": ["Research workspaces"], "description": "Requires stopped compute with confirmed release and no active file transfer. Send the complete configuration and its observed configuration_revision. Allows editor, SSH public key, GPU resources, session duration changes. Name, environment, project capacity and repository bootstrap remain fixed. Saved files and previous workloads are preserved. An exact retry of already applied settings succeeds. Conflicting changes require reloading and reviewing the current configuration.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Saved workspace identifier."} ], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "required": ["configuration_revision", "configuration"], "properties": { "configuration_revision": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "configuration": {"$ref": "#/components/schemas/ResearchWorkspaceConfiguration"} } }}} }, "responses": { "200": {"description": "Current workspace with saved settings", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}}}}, "default": {"description": "400 for invalid settings or revision. 404 for another account or missing workspace. 409 workspace_configuration_changed requires review of current settings. 409 workspace_configuration_busy requires compute and transfers to finish. Authentication and rate limits apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}}}} } }, "get": { "operationId": "getResearchWorkspace", "summary": "Read workspace state, costs and tool readiness", "tags": ["Research workspaces"], "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Saved workspace identifier."} ], "responses": { "200": { "description": "Current workspace view", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}} } }, "default": { "description": "404 if this account does not own the workspace. Authentication, rate limits and transient failures also apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/research-workspaces/{id}/transfers": { "post": { "operationId": "beginWorkspaceTransfer", "summary": "Begin a stopped-workspace file replacement", "tags": [ "Research workspaces" ], "description": "Available only when included-10gb-v1 or r2-standard-10gb-account-v1 is explicitly active for the deployment and workspace. Compute must be stopped. Requires a nonempty canonical version 3 archive manifest, not a generic archive upload. Retain idempotency_key, manifest and replace_revision together across retries. Previously saved files require the current storage_revision as replace_revision. Beginning a transfer does not change saved files. The SDK folder uploader prepares this canonical manifest and uploads bounded segments.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace identifier owned by this account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTransferRequest" } } } }, "responses": { "201": { "description": "Transfer created or original intent replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTransfer" } } } }, "default": { "description": "400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research-workspaces/{id}/transfers/{transfer}": { "get": { "operationId": "getWorkspaceTransfer", "summary": "Read upload and verification progress", "tags": [ "Research workspaces" ], "description": "Read state and uploaded_segments before resuming an interrupted upload. A committed transfer has replaced the guarded saved-file revision. Queued or verifying does not establish a successful save. Requires stopped compute and the active workspace storage policy.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace identifier owned by this account." }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer identifier returned by begin." } ], "responses": { "200": { "description": "Current transfer state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTransfer" } } } }, "default": { "description": "400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "abandonWorkspaceTransfer", "summary": "Abandon a pending file replacement", "tags": [ "Research workspaces" ], "description": "Abandons the transfer and schedules cleanup of its owned upload data. Existing saved files remain intact. A successful response does not claim that uncertain writes or their cleanup have completed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace identifier owned by this account." }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer identifier returned by begin." } ], "responses": { "204": { "description": "Transfer abandoned" }, "default": { "description": "400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research-workspaces/{id}/transfers/{transfer}/segments/{segment}": { "put": { "operationId": "uploadWorkspaceTransferSegment", "summary": "Upload one declared archive segment", "tags": [ "Research workspaces" ], "description": "Send the exact bytes identified by this zero-based segment index in the manifest. Content-Length is required and must match the declared segment. Content-Type must be exactly application/octet-stream. Chunked transfer encoding is not accepted. Segments are checked against their declared size and SHA256. Retry with the same transfer and segment after an uncertain reply.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace identifier owned by this account." }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer identifier returned by begin." }, { "name": "segment", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based manifest segment index." }, { "name": "Content-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 512, "maximum": 67108864, "multipleOf": 512 }, "description": "Exact segment byte length." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Exact declared canonical archive segment, at most 64 MiB." } } } }, "responses": { "204": { "description": "Segment accepted and verified" }, "default": { "description": "400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research-workspaces/{id}/transfers/{transfer}/finalize": { "post": { "operationId": "finalizeWorkspaceTransfer", "summary": "Queue verification of uploaded project files", "tags": [ "Research workspaces" ], "description": "Send an empty JSON object after every segment has been uploaded. A 202 response means verification is queued or still running. Poll the transfer until state is committed or abandoned. Repeating finalize returns 200 only once the transfer is committed. Verification checks the archive, inventory and unchanged replacement revision before publishing saved files.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace identifier owned by this account." }, { "name": "transfer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Transfer identifier returned by begin." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } }, "responses": { "200": { "description": "Files committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTransfer" } } } }, "202": { "description": "Verification pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTransfer" } } } }, "default": { "description": "400 for malformed input. 404 workspace_transfer_not_found for a missing or inaccessible transfer. 409 workspace_storage_inactive when the policy is disabled, or workspace_transfer_conflict when state, revision or retry identity changed. 413 workspace_storage_capacity when capacity is exhausted. 503 workspace_transfer_unavailable or workspace_storage_unavailable for transient failures. Authentication and rate limits apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research-workspaces/{id}/workloads": { "post": { "operationId": "submitWorkspaceWorkload", "summary": "Submit an independent workload from this project", "tags": ["Research workspaces"], "description": "Captures current project files from ready compute, or pins the last successful saved revision while stopped. The command uses that immutable project revision and the workspace environment image. Optional GPU overrides apply only to the submitted workload. Running workspace capture returns 409 workspace_save_pending until saving finishes. Source preparation returns 409 workspace_source_pending until its verified copy is ready. Saving has a 45-minute deadline. Each source preparation attempt has a 45-minute deadline, with up to three automatic attempts. Cleanup waits may extend total preparation. Console and SDK waiting pause local observation after 95 minutes by default while retaining the submission intent. Reuse the exact body and Idempotency-Key to check progress or retry an uncertain reply. Identical captured revisions reuse a source copy within the included account source pool. Exports exclude .nodus and .git. Regular files, empty directories and safe relative symbolic links within the project are preserved. Unsafe links and unsupported file types are rejected before admission. A 202 response means ordinary workload admission succeeded. It does not establish execution or completion. Later edits and stopping workspace compute do not stop an admitted workload. Both incur charges while running.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Workspace identifier owned by this account."}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}, "description": "Stable key for this logical submission and its captured source revision. Reuse the same body and key after saving is pending or the reply is uncertain."} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkspaceWorkloadRequest"}}}}, "responses": { "202": { "description": "Independent workload admitted or replayed", "headers": {"Idempotent-Replayed": {"description": "true when workload admission replays the original result.", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SubmitResult"}}} }, "409": { "description": "workspace_save_pending and workspace_source_pending request the same key and body again after Retry-After. workspace_source_quota requires freeing included source space through Assets and using a new submission key. workspace_capture_failed requires correcting the save failure and beginning a new submission. workspace_source_rejected requires correcting the project source and using a new submission key. workspace_source_failed requires resolving the reported preparation failure and using a new submission key after cleanup. workspace_source_removed means its reference was deleted and a new submission must prepare a new copy. workspace_no_saved_files requires adding project files. workspace_source_unavailable reports a source preparation failure. idempotency_conflict indicates a changed body for an existing key. Other state conflicts can also occur.", "headers": {"Retry-After": {"description": "Seconds until the next progress check when workspace_save_pending or workspace_source_pending is returned.", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}} }, "default": { "description": "400 for invalid command or GPU configuration. 402 for payment or credit requirements. 404 for a workspace outside this account. 503 when submission is unavailable. Ordinary workload admission checks, authentication, rate limits and transient failures also apply.", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/Error"}, {"$ref": "#/components/schemas/SandboxError"}]}}} } } }, "get": { "operationId": "listWorkspaceWorkloads", "summary": "List workloads submitted from this workspace", "tags": ["Research workspaces"], "description": "Returns up to 100 admitted workloads, newest first, with the captured source revision. Recoverable pending_submissions preserve their exact original request and retry key for explicit resume after reconnecting. Old submissions without a stored request descriptor may be absent from pending_submissions. source_storage reports the separate included source pool. Use the ordinary workload endpoints for logs, results, costs and cancellation.", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Workspace identifier owned by this account."}], "responses": { "200": {"description": "Admitted workspace workloads", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkspaceWorkloadList"}}}}, "default": {"description": "404 for a workspace outside this account. Authentication, rate limits and transient failures also apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/v1/research-workspaces/{id}/start": { "post": { "operationId": "startResearchWorkspace", "summary": "Start compute or reconnect to the current session", "tags": ["Research workspaces"], "description": "Uses the saved configuration and an operator-qualified immutable environment. Reconnects to an eligible existing named session or admits a replacement after the previous writer releases the project. No request body is required. 202 means accepted, not ready or guaranteed capacity. Read connections before opening tools. A restart restores saved files only, not process memory.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Saved workspace identifier."}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}, "description": "Stable key for this logical start. Reuse it after an uncertain response. Use a new key for a new start after stopping a previous session."} ], "responses": { "202": { "description": "Start accepted or replayed", "headers": { "Idempotent-Replayed": {"description": "true when the original start is replayed.", "schema": {"type": "string"}} }, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}} } }, "default": { "description": "400 for a missing retry key or invalid saved configuration. 402 for payment or credit requirements. 404 for a workspace not owned by this account. 409 for an existing writer, saving, state or idempotency conflict. 503 when admission or workspace compute is unavailable. Authentication, quotas, repository authorization, rate limits and transient failures also apply.", "content": { "application/json": { "schema": { "oneOf": [{"$ref": "#/components/schemas/SandboxError"}, {"$ref": "#/components/schemas/Error"}] } } } } } } }, "/v1/research-workspaces/{id}/schedule": { "post": { "operationId": "scheduleResearchWorkspace", "summary": "Schedule workspace readiness", "tags": ["Research workspaces"], "description": "Begins preparation 15 minutes before ready_by. Customer compute metering begins when readiness is observed. stop_at is optional.", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["ready_by"], "properties": {"ready_by": {"type": "string", "format": "date-time"}, "stop_at": {"type": "string", "format": "date-time"}}}}}}, "responses": {"201": {"description": "Wake plan created", "content": {"application/json": {"schema": {"type": "object"}}}}, "default": {"description": "Invalid schedule, active schedule, authentication or transient failure.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}} }, "delete": { "operationId": "cancelResearchWorkspaceSchedule", "summary": "Cancel workspace readiness schedule", "tags": ["Research workspaces"], "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}}], "responses": {"200": {"description": "Schedule cancelled", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}}}}} } }, "/v1/research-workspaces/{id}/stop": { "post": { "operationId": "stopResearchWorkspace", "summary": "Save project files and stop the specified compute session", "tags": ["Research workspaces"], "description": "Stops the original session_id, not whichever replacement session exists when a retry arrives. Preserve both session_id and Idempotency-Key for every retry. A new stop targeting a replacement requires a new pair. Returns the current workspace view, which may refer to a newer session during a delayed replay. Poll state and saving_for_termination to observe final-save and compute-release progress. A 200 response alone does not confirm supplier resource release. Retained storage is not deleted.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Saved workspace identifier."}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1}, "description": "Stable retry key paired with the original session_id in the request body."} ], "requestBody": { "required": true, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceStopRequest"}} } }, "responses": { "200": { "description": "Stop handled or replayed without a pending final save. Inspect workspace state for compute-release progress.", "headers": { "Idempotent-Replayed": {"description": "true when the original stop is replayed.", "schema": {"type": "string"}} }, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}} } }, "202": { "description": "Final project save remains pending before compute release", "headers": { "Idempotent-Replayed": {"description": "true when the original stop is replayed.", "schema": {"type": "string"}} }, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspace"}} } }, "default": { "description": "400 for a missing retry key, missing body or invalid session_id. 404 for a workspace or session outside this account, or a session belonging to another workspace. 409 for a state or idempotency conflict. Authentication, rate limits and transient failures also apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/research-workspaces/{id}/connections": { "post": { "operationId": "connectResearchWorkspace", "summary": "Open a ready browser tool or get desktop SSH configuration", "tags": ["Research workspaces"], "description": "Requires a current authorized compute session with reachable, healthy tools. editor and notebook return a one-time HTTPS URL. ssh requires a saved SSH public key and returns OpenSSH configuration, using either the authenticated HTTPS proxy command or a direct gateway with a known_hosts entry. Browser tools use isolated per-tool origins, not the API or console origin. Account credentials never reach the guest. Revocation, session replacement or expired authorization closes access, including active browser streams. Closing a client does not stop compute.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Saved workspace identifier."} ], "requestBody": { "required": true, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceConnectionRequest"}} } }, "responses": { "200": { "description": "One-time browser connection URL or desktop SSH configuration, depending on tool", "content": { "application/json": { "schema": { "oneOf": [{"$ref": "#/components/schemas/ResearchWorkspaceBrowserConnection"}, {"$ref": "#/components/schemas/ResearchWorkspaceSSHConnection"}, {"$ref": "#/components/schemas/WorkspaceWebSocketSSHConnection"}] } } } }, "default": { "description": "400 for an invalid tool. 404 for a workspace not owned by this account. 409 workspace_not_ready until the session and tools are ready. 503 if browser access or SSH configuration is unavailable. Authentication, rate limits and transient failures also apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/research-workspaces/{id}/ssh-stream": { "get": { "operationId": "streamWorkspaceSSH", "summary": "Connect an authenticated SSH stream to the current workspace session", "tags": ["Research workspaces"], "description": "Upgrades an authenticated request to a WebSocket using nodus-workspace-ssh-v1. Binary messages carry the SSH byte stream. Use the session and generation from a fresh SSH connection response. Query strings, Origin and Cookie headers are rejected. Authorization must contain one current Bearer credential. Nodus checks workspace ownership and the pinned session before connecting and while forwarding. The guest still authenticates the customer's SSH public key. Either side closing or authorization expiry closes the stream. The CLI proxy opens this endpoint without a browser or credential in its command line.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-Nodus-Workspace-Session", "in": "header", "required": true, "schema": {"type": "string"}, "description": "Pinned compute session identifier from the SSH connection response."}, {"name": "X-Nodus-Workspace-Generation", "in": "header", "required": true, "schema": {"type": "string", "pattern": "^[1-9][0-9]*$"}, "description": "Exact positive decimal session generation from the SSH connection response."}, {"name": "Sec-WebSocket-Protocol", "in": "header", "required": true, "schema": {"type": "string", "const": "nodus-workspace-ssh-v1"}} ], "responses": { "101": {"description": "Authenticated binary SSH stream. The standard WebSocket handshake headers apply."}, "default": {"description": "400 invalid_ssh_connection for an invalid handshake identity. 409 workspace_not_ready for a stale or unavailable session. 503 ssh_unavailable when the stream or guest is unavailable. Authentication and rate limits also apply.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}}}} } } }, "/v1/research-workspaces/{id}/connections/retry": { "post": { "operationId": "retryResearchWorkspaceConnection", "summary": "Retry one browser connection without restarting compute", "tags": ["Research workspaces"], "description": "Explicitly schedules a safe retry for the selected tool on the current workspace session. It does not issue a connection URL, start compute or guarantee that the tool is ready. An uncertain remote operation cannot be retried until its outcome is reconciled. After acceptance, read the workspace again and use its connection readiness before opening the tool. A rejected retry does not prevent stopping compute. Available only when the deployment enables connection retry.", "parameters": [ {"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Research workspace identifier owned by this account."} ], "requestBody": { "required": true, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceConnectionRetryRequest"}} } }, "responses": { "202": { "description": "Retry scheduled. This is not a ready connection or browser grant.", "headers": { "Cache-Control": {"schema": {"type": "string", "const": "no-store"}} }, "content": { "application/json": {"schema": {"$ref": "#/components/schemas/ResearchWorkspaceConnectionRetry"}} } }, "default": { "description": "400 invalid_tool, invalid_json or invalid_body for invalid input. 404 not_found for an unavailable owned workspace. 409 connection_not_retryable when a safe retry cannot be scheduled. 503 connection_unavailable when disabled or gateway authority is unavailable. 500 connection_retry_failed for an unexpected internal failure. Authentication and rate limits also apply.", "content": { "application/json": {"schema": {"$ref": "#/components/schemas/SandboxError"}} } } } } }, "/v1/workspaces": { "post": { "operationId": "createWorkspace", "summary": "Create a named persistent workspace", "tags": [ "Workspaces" ], "description": "Creates an empty tenant-owned workspace. A matching name and size replays the existing identity. Capacity and team count limits apply. Storage billing is disabled until an approved storage rate is configured.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRecord" } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } }, "get": { "operationId": "listWorkspaces", "summary": "List owned workspace metadata", "description": "Returns a page ordered by workspace name and identifier. The default and maximum page size are 1000. Continue with next_cursor until it is empty. Saved workspaces remain visible after compute stops. Pages reflect current records and do not form a snapshot across concurrent changes.", "tags": [ "Workspaces" ], "parameters": [ {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 1000}, "description": "Maximum workspaces on this page."}, {"name": "cursor", "in": "query", "schema": {"type": "string", "maxLength": 1024}, "description": "Opaque next_cursor from this account's previous workspace page."} ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspaces" ], "properties": { "workspaces": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/WorkspaceRecord" } }, "next_cursor": { "type": "string", "maxLength": 1024, "description": "Opaque continuation for this account and list. Empty when this page has no further records." } } } } } }, "default": { "description": "Error. The code, message, and fix fields describe the rejection and its remedy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/pools": { "post": { "operationId": "createPool", "summary": "Create a pool for read-only measurement", "tags": [ "Pools" ], "responses": { "201": { "description": "Create a pool for read-only measurement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pool" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolCreateRequest" } } } }, "description": "The pool belongs to the authenticated team. This operation has no idempotency contract. Inspect the pool list after a timeout before repeating creation." }, "get": { "operationId": "listPools", "summary": "List the authenticated team's pools", "tags": [ "Pools" ], "responses": { "200": { "description": "List the authenticated team's pools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolList" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/pools/{id}": { "get": { "operationId": "getPool", "summary": "Read pool configuration", "tags": [ "Pools" ], "responses": { "200": { "description": "Read pool configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pool" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ] }, "patch": { "operationId": "updatePool", "summary": "Update a pool name or owned hardware cost", "tags": [ "Pools" ], "responses": { "200": { "description": "Update a pool name or owned hardware cost", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pool" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolPatchRequest" } } } }, "description": "Only name and owned_cost_micros_per_hour can be changed. Predict and Route cannot be enabled." } }, "/v1/pools/{id}/enrollment-tokens": { "post": { "operationId": "createPoolEnrollmentToken", "summary": "Issue a single-use host enrollment token", "tags": [ "Pools" ], "responses": { "201": { "description": "Issue a single-use host enrollment token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolEnrollmentToken" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolEnrollmentTokenRequest" } } } }, "description": "The secret expires after 24 hours. Observe enrollment is the default. Explicit execute reenrollment binds one existing host and rotates its credential when used. It can be prepared before enabling Route. Requests are not idempotent and must not be automatically replayed." } }, "/v1/pools/{id}/hosts": { "get": { "operationId": "listPoolHosts", "summary": "List hosts with health and device inventory", "tags": [ "Pools" ], "responses": { "200": { "description": "List hosts with health and device inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolHostList" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ] } }, "/v1/pools/{id}/hosts/{host}/drain": { "post": { "operationId": "drainPoolHost", "summary": "Request host drain", "tags": [ "Pools" ], "responses": { "200": { "description": "Request host drain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolHost" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "host", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ], "description": "Marks the host draining. The observe agent receives desired drain state. Customer processes continue running." } }, "/v1/pools/{id}/hosts/{host}": { "delete": { "operationId": "removePoolHost", "summary": "Remove a host and revoke its credential", "tags": [ "Pools" ], "responses": { "204": { "description": "Remove a host and revoke its credential" }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "host", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." } ], "description": "Preserves historical measurements. Removal does not stop customer processes or uninstall the agent." } }, "/v1/pools/{id}/utilization": { "get": { "operationId": "getPoolUtilization", "summary": "Read customer pool utilization from retained device hours", "tags": [ "Pools" ], "responses": { "200": { "description": "Retained utilization and explicit measurement availability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolUtilization" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Malformed, duplicate or unsupported query fields or invalid time range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Result exceeds the full-response bound. Narrow the time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive RFC3339 UTC-hour boundary. Defaults to 168 hours before to." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive RFC3339 UTC-hour boundary. Defaults to the current UTC hour." }, { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day" ], "default": "hour" }, "description": "Group retained hours by hour or UTC calendar day." } ], "description": "Read-only and available to account members. Defaults to the last 168 complete hours, ending at the current UTC hour. From is inclusive and to is exclusive. Both must align to UTC hours and the window must be positive and at most 31 days. Future or incomplete hours are rejected. Day buckets follow UTC calendar boundaries and may have shorter first or last buckets. The response includes current hosts without evidence and removed hosts with retained history. Queries never read raw telemetry. Requests over 100000 device-hour rows or host buckets return 422 instead of partial totals. Narrow the time window to retry." } }, "/v1/pools/{id}/forecast": { "get": { "operationId": "getPoolForecast", "summary": "Read a pool forecast and its calibration", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "horizon", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 30 } } ], "responses": { "200": { "description": "Read a pool forecast and its calibration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolForecastResponse" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Snapshot is null until the first refresh. Cached data remains readable while disabled or paused. Forecast availability is separate from empirical calibration availability." } }, "/v1/pools/{id}/recommendations": { "get": { "operationId": "getPoolRecommendations", "summary": "Read advisory pool recommendations", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque next_cursor returned for the same pool and state filter." }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "open", "done", "expired" ] }, "description": "Optional lifecycle filter. Open records that have passed their expiry are treated as expired." } ], "responses": { "200": { "description": "Read advisory pool recommendations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolRecommendationsResponse" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Read advice and human-reported outcomes for this customer-owned pool. Results use keyset pagination in descending creation order. No execution or automatic action is performed." } }, "/v1/pools/{id}/recommendations/{rid}/done": { "post": { "operationId": "completePoolRecommendation", "summary": "Record a manual recommendation outcome", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "rid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Record a manual recommendation outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolRecommendationOutcome" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolRecommendationDone" } } } }, "description": "Requires an admin. Replaying the same outcome returns the original result. A conflicting replay or an expired recommendation returns 409. This records a customer action and does not execute infrastructure changes." } }, "/v1/pools/{id}/proposals": { "get": { "operationId": "listPoolProposals", "summary": "Read retained burst proposals", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque next_cursor returned for the same pool and state filter." }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "no_op", "applying", "applied" ] }, "description": "Optional lifecycle filter. Active records that passed their expiry are returned as expired." } ], "responses": { "200": { "description": "Retained burst proposals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolProposalsResponse" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Read burst intent for this customer-owned pool, including expired and no-op outcomes. Reads do not require Predict. Keyset pagination uses descending creation order. Follow next_cursor with the same pool and state filter." } }, "/v1/pools/{id}/proposals/{pid}/approve": { "post": { "operationId": "approvePoolProposal", "summary": "Approve a burst proposal", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmed retained proposal decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolProposal" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "description": "Requires a current account admin and active Route authorization. Send an empty object or omit the body. The proposed amount cannot be changed. The decision is retained atomically. Replays return the same confirmed decision. Expired, no-op, or conflicting decisions return 409. Approval records intent only and does not itself rent capacity. New admission must revalidate the current quote against the approved amount and original expiry." } }, "/v1/pools/{id}/proposals/{pid}/reject": { "post": { "operationId": "rejectPoolProposal", "summary": "Reject a burst proposal", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirmed retained proposal decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolProposal" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "description": "Requires a current account admin and active Route authorization. Send an empty object or omit the body. The proposed amount cannot be changed. The decision is retained atomically. Replays return the same confirmed decision. Expired, no-op, or conflicting decisions return 409. Approval records intent only and does not itself rent capacity. New admission must revalidate the current quote against the approved amount and original expiry." } }, "/v1/pools/{id}/action-policies": { "get": { "operationId": "getPoolActionPolicies", "summary": "Read action policies and shadow readiness", "description": "Members may read settings. Readiness never grants execution authority.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read action policies and shadow readiness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActionSettings" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setPoolActionPolicy", "summary": "Set one complete action policy", "description": "Requires an account admin. Approve and auto require active Predict and Route with accepted current terms and the kill switch off. Auto also requires a recent complete trusted matching shadow cycle. Off and recommend can be saved without activation. Recommendations require Predict. Saving a policy does not execute an action.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Set one complete action policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActionSettings" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActionPolicyRequest" } } } } } }, "/v1/pools/{id}/act-kill-switch": { "put": { "operationId": "setPoolActKillSwitch", "summary": "Set the Act kill switch", "description": "Requires an account admin. Available even after entitlement loss. Enabling the kill switch blocks new Act authorization and preserves existing resource cleanup.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Set the Act kill switch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActionSettings" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActKillSwitchRequest" } } } } } }, "/v1/pools/{id}/shadow-runs": { "get": { "operationId": "listPoolShadowRuns", "summary": "Read trusted shadow coverage and gaps", "description": "Members may read retained cycles. Keyset pagination is bound to the same pool and kind. A gap is a completed elapsed hour without trusted evidence.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] } } ], "responses": { "200": { "description": "Read trusted shadow coverage and gaps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolShadowRuns" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "startPoolShadowRun", "summary": "Start a future shadow observation cycle", "description": "Requires an account admin, active Predict, active Route authorization and the kill switch off. Starts at the next complete UTC hour and runs for 168 hours. Starting the same configuration within one hour returns the existing cycle. No action is applied by shadow mode.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Start a future shadow observation cycle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolShadowRun" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActionPolicyRequest" } } } } } }, "/v1/pools/{id}/action-proposals": { "get": { "operationId": "listPoolActionProposals", "summary": "Read Act intent and observed outcomes", "description": "Members may read retained action proposals. Follow next_cursor with the same pool and kind. Approval is not evidence that an action was applied. Internal claims, actor identities and source hashes are omitted.", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "idle_reclaim", "defragment", "drain_window", "wait_tuning" ] } } ], "responses": { "200": { "description": "Retained Act proposals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActProposals" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/pools/{id}/action-proposals/{pid}/approve": { "post": { "operationId": "approvePoolActionProposal", "summary": "Approve a retained Act proposal", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retained Act decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActProposal" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "description": "Requires an account admin. Send an empty object or omit the body. The server retains immutable action evidence. Approval rechecks active Predict, Route, policy and expiry. Dispatch rechecks authority separately. A stale proposal records no-op or expired state and returns a conflict. Rejection does not apply an action." } }, "/v1/pools/{id}/action-proposals/{pid}/reject": { "post": { "operationId": "rejectPoolActionProposal", "summary": "Reject a retained Act proposal", "tags": [ "Pools" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier returned by Nodus." }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retained Act decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolActProposal" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "description": "Requires an account admin. Send an empty object or omit the body. The server retains immutable action evidence. Approval rechecks active Predict, Route, policy and expiry. Dispatch rechecks authority separately. A stale proposal records no-op or expired state and returns a conflict. Rejection does not apply an action." } }, "/v1/workloads/{id}/freeze": { "post": { "operationId": "freezeWorkload", "summary": "Request saved-file workload freeze", "description": "Requires a running checkpointed batch workload with useful saved state and a compatible runner. Freeze returns intent until checkpoint and exact compute cleanup are confirmed. Resume requires completed cleanup, preserves selected saved files and restarts the same customer command. Storage bytes are reported separately from unknown storage charges.", "tags": [ "Workloads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Request saved-file workload freeze", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkloadFreeze" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getWorkloadFreeze", "summary": "Read retained checkpoint and freeze state", "description": "Read retained freeze state for a workload on your account. Retained storage is not separately metered and no storage charge is reported.", "tags": [ "Workloads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read retained checkpoint and freeze state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkloadFreeze" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workloads/{id}/resume": { "post": { "operationId": "resumeWorkload", "summary": "Resume the command with retained checkpoint files", "description": "Requires a running checkpointed batch workload with useful saved state and a compatible runner. Freeze returns intent until checkpoint and exact compute cleanup are confirmed. Resume requires completed cleanup, preserves selected saved files and restarts the same customer command. Storage bytes are reported separately from unknown storage charges.", "tags": [ "Workloads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Resume the command with retained checkpoint files", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkloadFreeze" } } } }, "default": { "description": "Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workloads/{id}/rl-grading-results": { "get": { "operationId": "getWorkloadRLGradingResults", "summary": "Read verified public grading receipts", "tags": [ "Workloads" ], "description": "Read a consistent snapshot of grading attempts for one parent workload revision in the authenticated tenant. Requires a server-admitted private grading plan. This endpoint does not enable private-code training. It excludes private cases, candidate source, runner credentials and grading child identities. Receipts are verified before publication and a corrupt snapshot returns an error. Cleanup covers only the requested revision's grading attempts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": "One explicit parent revision. Duplicate revision parameters and other query parameters are rejected." } ], "responses": { "200": { "description": "Verified grading snapshot", "headers": { "Cache-Control": { "description": "Grading evidence must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLGradingResults" } } } }, "400": { "description": "Invalid or missing revision. Error code is invalid_revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No grading plan exists for this parent workload revision in the authenticated tenant. Grading children are not accessible through this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The grading snapshot could not be verified or read. Error code is grading_results_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, rate limits and transient failures apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workloads/{id}/rl-summary": { "get": { "operationId": "getRLSummary", "summary": "Summarize an RL run's scored tasks and before-and-after comparison", "tags": [ "RL" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLSummary" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Counts every reported attempt once, as its latest report, per phase, and compares baseline with evaluation the way the console's run page does. comparable is false when the phases scored different numbers of attempts or different tasks. measurable is false when the phases are not comparable or every attempt passed or failed in both. When dropped_events is above zero or truncated is true, reason is incomplete_events and neither is true, because missing events could change either score. resolution_pp is the smallest change the task count can show. Figures come from events the workload reported and do not establish general model improvement." } }, "/v1/workloads/{id}/rl-events": { "get": { "operationId": "listWorkloadRLEvents", "summary": "Read recorded RL task evidence", "tags": [ "Workloads" ], "description": "Read typed task events for a workload in the authenticated tenant. Inherits the customer bearer authentication used by other workload operations. Events are reported by the customer runner and persisted by Nodus, not independently measured by this endpoint. The workload must carry RL metadata and its command must emit task events to produce evidence. A workload without recorded events returns an empty page. Follow has_more to drain available pages, then continue polling next_cursor while the workload is active. Read workload status separately and perform a fresh final drain after it becomes terminal. This endpoint does not install or launch a catalog environment and does not provide built-in training.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workload identity in the authenticated tenant." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Opaque exclusive replay cursor from a previous next_cursor. Omit it to begin at the first recorded event. Pass it unchanged and do not use a numeric row ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "Maximum number of event rows in this page." } ], "responses": { "200": { "description": "Persisted RL event page", "headers": { "Cache-Control": { "description": "Task evidence must not be cached.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLEventPage" } } } }, "400": { "description": "Invalid cursor or page size. Error codes are invalid_cursor or invalid_limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The workload does not exist in the authenticated tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, rate limits and transient failures apply. The JSON error and message fields describe the failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rl-environments/{environment}": { "get": { "operationId": "getRLEnvironment", "summary": "Read one RL environment and its runnable examples", "tags": [ "RL" ], "parameters": [ { "name": "environment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Environment id from GET /v1/rl-environments, such as gsm8k." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLEnvironment" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "The same entry GET /v1/rl-environments lists. 404 means no environment has that id." } }, "/v1/rl-environments/{environment}/examples/{example}/workload": { "get": { "operationId": "getRLExampleWorkload", "summary": "Read the run an example would submit, without starting it", "tags": [ "RL" ], "parameters": [ { "name": "environment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Environment id from GET /v1/rl-environments, such as gsm8k." }, { "name": "example", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Example id from that environment, such as gsm8k-trained." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workload": { "$ref": "#/components/schemas/WorkloadPayload" } }, "required": [ "workload" ] } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Returns the workload POST .../runs submits with the default name. Review it, check it with POST /v1/workloads/validate, or change it, such as its GPU, and submit it with POST /v1/workloads. Starts nothing and charges nothing. 404 means no runnable example has these ids." } }, "/v1/rl-environments/{environment}/examples/{example}/runs": { "post": { "operationId": "runRLExample", "summary": "Start an RL example in one request", "tags": [ "RL" ], "parameters": [ { "name": "environment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Environment id from GET /v1/rl-environments, such as gsm8k." }, { "name": "example", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Example id from that environment, such as gsm8k-trained." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required stable key per logical run. Retrying with the same key returns the original run instead of starting another." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 120, "description": "Run name. Defaults to the environment and example names." } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } }, "headers": { "Idempotent-Replayed": { "description": "true on a replay of the original run.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Submits the run the example describes: its command through a shell, its runtime image, a GPU with at least peak_memory_gb, its result files and its RL details with example_id. A retry is matched by environment, example and name under the Idempotency-Key, so it returns the original run even if the catalog changed in between. Omitting name means the example's default name. The same key with a different example or name returns 409. It is an ordinary workload. Follow it with GET /v1/workloads/{id}, its RL events and its outputs. 404 means no runnable example has these ids. Admission, spending checks and errors are those of POST /v1/workloads." } }, "/v1/rl-environments": { "get": { "operationId": "listRLEnvironments", "summary": "Discover RL environments and the examples you can run", "tags": [ "RL" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "reviewed_at": { "type": "string" }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/RLEnvironment" } } }, "required": [ "schema_version", "environments" ] } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rl-recipes": { "get": { "operationId": "listRLRecipes", "summary": "Discover managed RL recipes and availability", "tags": [ "RL" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/RLRecipeDescriptor" } } }, "required": [ "recipes" ] } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rl-runs/preview": { "post": { "operationId": "previewRLRun", "summary": "Review an RL setup without reserving compute", "tags": [ "RL" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLRunPreview" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLRecipeRequest" } } } }, "description": "Authenticates the caller and prepares a server-owned recipe. Preview does not create a workload or reserve compute. An unavailable estimate is not a zero cost estimate. Launchability remains subject to current billing and capacity checks at submission and provisioning." } }, "/v1/rl-runs": { "post": { "operationId": "createRLRun", "summary": "Launch the reviewed managed RL recipe", "tags": [ "RL" ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } }, "headers": { "Idempotent-Replayed": { "description": "true on a replay of the original submission.", "schema": { "type": "string" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RLRunRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Required stable key per logical submission. Replay the same payload with the same key. Different payload returns 409." } ], "description": "Uses ordinary workload admission, billing and tenant ownership. 202 confirms acceptance. Reuse the exact body and Idempotency-Key after an uncertain response. A changed configuration or runtime returns 409 review_changed. After an earlier uncertain submission, keep the original key and check existing runs before starting another attempt. 503 rl_unavailable means new managed launches are paused or the runtime is unqualified. A completed run does not by itself establish improved model quality." } }, "/v1/connections": { "post": { "operationId": "createConnection", "summary": "Verify and create an external connection", "tags": [ "Connections" ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "default": { "description": "Connection operation rejected. Errors never include credential values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Verifies within five seconds before saving an immutable credential version. Only public TLS endpoints are accepted. Database verification uses SELECT 1 in a read-only transaction. Secret rotation or revocation prevents new uses of the old connection. Create a new connection to adopt a new secret version.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } } } }, "get": { "operationId": "listConnections", "summary": "List external connection metadata", "tags": [ "Connections" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "connections" ], "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } } } } } } }, "default": { "description": "Connection operation rejected. Errors never include credential values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections/{id}": { "get": { "operationId": "getConnection", "summary": "Get an external connection", "tags": [ "Connections" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "default": { "description": "Connection operation rejected. Errors never include credential values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connection name or ID.", "schema": { "type": "string" } } ] }, "delete": { "operationId": "deleteConnection", "summary": "Delete an external connection", "description": "Removes the connection from listing and future use. Returns 409 while a workload, export, load or metadata refresh is active. Completed workload and transfer history is retained. Stored credentials and external data are unchanged.", "tags": [ "Connections" ], "responses": { "204": { "description": "Success" }, "default": { "description": "Connection operation rejected. Errors never include credential values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connection name or ID.", "schema": { "type": "string" } } ] } }, "/v1/connections/{id}/verify": { "post": { "operationId": "verifyConnection", "summary": "Reverify a connection using its active pinned credential", "tags": [ "Connections" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "default": { "description": "Connection operation rejected. Errors never include credential values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Connection name or ID.", "schema": { "type": "string" } } ] } }, "/v1/workloads/{id}/outputs/{name}/reload": { "post": { "operationId": "reloadWorkloadOutput", "summary": "Retry a database sink load", "tags": [ "Workloads" ], "description": "Retry the latest saved output using its immutable admission credential. A pending or loading job is reused. Supply stage when names repeat.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "name" }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required to disambiguate duplicate output names across stages. Otherwise 409 ambiguous_output." } ], "responses": { "202": { "description": "Load pending or already loading", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionLoad" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workloads/validate": { "post": { "tags": [ "Workloads" ], "summary": "Validate a prepared workload without submitting it", "operationId": "validateWorkload", "description": "Checks the workload request and referenced resources without admission, capacity reservation or spending. A valid request can still fail admission when submitted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkloadPayload" } } } }, "responses": { "200": { "description": "Request is valid and has not been submitted", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "submitted", "workload", "message" ], "properties": { "valid": { "type": "boolean", "enum": [ true ] }, "submitted": { "type": "boolean", "enum": [ false ] }, "workload": { "$ref": "#/components/schemas/WorkloadPayload" }, "message": { "type": "string" } } } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/operations/{version}": { "get": { "operationId": "listOperations", "summary": "Discover versioned workload and draft operations", "tags": [ "Operations" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "v1" ] }, "description": "Operation contract version. Unknown versions return 404." } ], "responses": { "200": { "description": "The operations supported by this API transport. Discovery does not grant execution permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCatalog" } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/operations/{version}/{operation}": { "post": { "operationId": "invokeOperation", "summary": "Invoke a versioned workload, sandbox, managed-agent or draft operation", "tags": [ "Operations" ], "description": "Workload operations use the same handlers as the direct routes. The authenticated credential determines team and member access. Submit requires a stable idempotency_key in the JSON arguments. Retry identical arguments after an uncertain response. Validation starts no compute and does not guarantee admission. Logs return text. Workload operations preserve their direct-route JSON response shape. Run drafts require a member-attributed credential and are isolated by team and member. Updates require expected_revision and a partial patch. Omitted fields remain unchanged and null removes a field. An immediate identical retry returns its saved revision. A conflicting edit returns HTTP 409 with run_draft_conflict. Draft operations do not submit workloads or authorize spending. Unsupported operations or versions return 404. Sandbox and managed-agent operations use the same owning handlers as their direct routes and return their existing receipts. All mutations in these families require caller-stable idempotency keys. Live file reads run a helper and can wake paid compute. Observation tools never wait for execution completion.", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "v1" ] }, "description": "Operation contract version. Unknown versions return 404." }, { "name": "operation", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "workloads.list", "workloads.get", "workloads.events", "workloads.logs", "workloads.outputs", "workloads.validate", "run_draft.get", "workloads.submit", "workloads.cancel", "run_draft.update", "sandboxes.capabilities", "sandboxes.templates", "sandboxes.create", "sandboxes.list", "sandboxes.get", "sandboxes.exec", "sandboxes.exec_get", "sandboxes.exec_output", "sandboxes.exec_cancel", "sandboxes.files", "sandboxes.sleep", "sandboxes.wake", "sandboxes.terminate", "agents.create", "agents.update", "agents.list", "agents.get", "agents.submit", "agents.runs", "agents.run_get", "agents.run_steps", "agents.signal", "agents.pause", "agents.resume", "agents.run_retry", "agents.run_cancel" ] }, "description": "Canonical operation identifier from the catalog." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationArguments" } } } }, "responses": { "200": { "description": "Read, validation or saved draft result. The result schema depends on the operation.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "workloads": { "type": "array", "items": { "$ref": "#/components/schemas/WorkloadListItem" } }, "next_offset": { "type": "integer" } }, "required": [ "workloads" ] }, { "allOf": [ { "$ref": "#/components/schemas/Workload" }, { "type": "object", "required": [ "id", "status", "revision" ] } ] }, { "type": "object", "properties": { "events": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WorkloadEvent" } } }, "required": [ "events" ] }, { "type": "object", "properties": { "workload_id": { "type": "string" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/Output" } } }, "required": [ "workload_id", "outputs" ] }, { "$ref": "#/components/schemas/WorkloadValidationResult" }, { "$ref": "#/components/schemas/RunDraft" }, { "type": "object", "required": [ "available", "default_template", "templates" ], "properties": { "available": { "type": "boolean" }, "default_template": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object" } }, "reason": { "type": "string" } } }, { "type": "object", "required": [ "sandboxes", "next_cursor" ], "properties": { "sandboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Sandbox" } }, "next_cursor": { "type": [ "string", "null" ] } } }, { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "type": "object", "required": [ "id" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/SandboxExec" }, { "type": "object", "required": [ "id" ] } ] }, { "$ref": "#/components/schemas/SandboxOutputPage" }, { "type": "object", "additionalProperties": false, "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgent" } }, "next_after": { "type": "string" } }, "required": [ "agents", "next_after" ] }, { "allOf": [ { "$ref": "#/components/schemas/ManagedAgent" }, { "type": "object", "required": [ "id" ] } ] }, { "type": "object", "additionalProperties": false, "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRun" } }, "next_after": { "type": "string" } }, "required": [ "runs", "next_after" ] }, { "allOf": [ { "$ref": "#/components/schemas/ManagedAgentRun" }, { "type": "object", "required": [ "id" ] } ] }, { "$ref": "#/components/schemas/AgentStepPage" } ] } }, "text/plain": { "schema": { "type": "string" } } } }, "202": { "description": "Submission accepted or cancellation requested. Acceptance is not completion.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubmitResult" }, { "type": "object", "properties": { "status": { "type": "string", "const": "cancel_requested" } }, "required": [ "status" ] }, { "allOf": [ { "$ref": "#/components/schemas/Sandbox" }, { "type": "object", "required": [ "id" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/SandboxExec" }, { "type": "object", "required": [ "id" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/ManagedAgent" }, { "type": "object", "required": [ "id" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/ManagedAgentRun" }, { "type": "object", "required": [ "id" ] } ] } ] } } } }, "default": { "description": "Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/managed-models/catalog": { "get": { "operationId": "listManagedModelCatalog", "summary": "Discover account-qualified managed models and prices", "tags": [ "Managed models" ], "description": "Requires a Nodus API key or console session. Returns only qualified Messages models explicitly granted to this account. Accounts without configured access receive enabled false and an empty models array. Discovery does not start compute or make a model call. Prices are customer USD micros per million tokens and include the service markup. Managed model access does not install agent harnesses or inject credentials into hosted workers.", "parameters": [], "responses": { "200": { "description": "Qualified catalog, including an empty catalog when access is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModelCatalog" } } } }, "default": { "description": "Authentication, request-rate or transient failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/managed-models/requests/{id}": { "get": { "operationId": "getManagedModelRequest", "summary": "Read a durable managed model billing receipt", "tags": [ "Managed models" ], "description": "Returns a receipt owned by the authenticated account. Running or unknown requests keep their spending reservation until reconciled. The receipt contains usage and charge evidence without the prompt or generated answer. It is not a response replay endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Receipt ID from X-Nodus-Request-ID or an accepted replay response." } ], "responses": { "200": { "description": "Durable request accounting state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModelReceipt" } } } }, "404": { "description": "The receipt does not exist in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication or accounting access failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/managed-models/messages": { "post": { "operationId": "createManagedModelMessage", "summary": "Generate a nonstreaming managed model message", "tags": [ "Managed models" ], "description": "Requires a Nodus API key or console session and an account-qualified catalog model. No customer model-provider key is required. Send JSON without query parameters or Content-Encoding. New requests reserve prepaid Nodus credits under account spending limits before dispatch. The reservation covers the full qualified input window and requested output limit, so it can exceed the final charge. Unused credit is released after settlement. Model usage is billed separately from compute and saved storage. Every logical call requires a stable Idempotency-Key. Preserve the key and body after an uncertain response. An accepted replay returns 409 with the existing billing receipt and never executes again or replays the answer. A different body using the same key returns an idempotency conflict. Persist received answers in your application. Unknown outcomes retain reserved funds and do not authorize a new-key retry. This endpoint does not install agent harnesses or inject credentials into hosted workers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "description": "Stable identifier for one logical model call. Reuse the same key and exact body after an uncertain response. A retry never authorizes another paid model call." } ], "requestBody": { "required": true, "description": "At most 1 MiB of JSON. Native model limits still apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModelMessagesRequest" } } } }, "responses": { "200": { "description": "Model response received and its verified usage charge committed.", "headers": { "X-Nodus-Request-ID": { "description": "Durable request receipt ID, returned after reservation is accepted.", "schema": { "type": "string" } }, "X-Nodus-Price-Version": { "description": "Immutable customer price version used for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModelCompletionResponse" } } } }, "400": { "description": "Missing or invalid stable idempotency key, unsupported request format, or request outside the bounded nonstreaming text/function-tool contract.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A valid Nodus API key or console session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient unreserved prepaid credits or account spending allowance. No new model request is dispatched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The authenticated user no longer has account write access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Model is not in this account’s qualified catalog or uses a different protocol.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Previously accepted request returns its durable receipt without another model call or answer replay. A conflicting key, request or price version returns an ordinary error.", "headers": { "X-Nodus-Request-ID": { "description": "Durable request receipt ID, returned after reservation is accepted.", "schema": { "type": "string" } }, "X-Nodus-Price-Version": { "description": "Immutable customer price version used for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ManagedModelReplay" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "413": { "description": "The model request exceeds the supported body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Nodus account request rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Definitive rejection posts no model charge and releases the reservation. A missing response or uncertain usage returns model_outcome_unknown and keeps its reservation. Inspect the receipt and preserve the request identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Model access or accounting admission is unavailable, or model_accounting_pending means a received response could not be durably settled. Inspect an accepted request receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, accounting and transient failures use the standard error shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/managed-models/chat/completions": { "post": { "operationId": "createManagedModelChatCompletion", "summary": "Recover a previously accepted managed chat completion receipt", "tags": [ "Managed models" ], "description": "This compatibility route only recovers previously accepted receipts. New model calls must use a catalog-qualified Messages model through /v1/managed-models/messages. Requires a Nodus API key or console session. Reuse the original Idempotency-Key and request body to receive HTTP 409 with the existing receipt. Replay does not execute again or return the answer body. A different body or protocol with the same key returns an idempotency conflict. Unknown outcomes retain reserved credits for reconciliation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "description": "Stable identifier for one logical model call. Reuse the same key and exact body after an uncertain response. A retry never authorizes another paid model call." } ], "requestBody": { "required": true, "description": "At most 1 MiB of JSON. Native model limits still apply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedModelChatCompletionRequest" } } } }, "responses": { "400": { "description": "Missing or invalid stable idempotency key, unsupported request format, or an invalid JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "A valid Nodus API key or console session is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The authenticated user no longer has account write access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No matching historical receipt was found and this route does not accept new model calls. Use a catalog-qualified Messages model through /v1/managed-models/messages for new work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The original key and body recover the previously accepted receipt without another model call or answer replay. Reusing the key with a different body or protocol returns an idempotency conflict.", "headers": { "X-Nodus-Request-ID": { "description": "Durable request receipt ID, returned after reservation is accepted.", "schema": { "type": "string" } }, "X-Nodus-Price-Version": { "description": "Immutable customer price version used for this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ManagedModelReplay" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "413": { "description": "The model request exceeds the supported body size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Nodus account request rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Receipt lookup is temporarily unavailable, or no matching historical receipt exists and managed model access is not enabled for this account. Preserve the original request identity when retrying receipt recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, accounting and transient failures use the standard error shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox-templates": { "get": { "operationId": "sandboxTemplates", "summary": "Discover qualified sandbox environments", "tags": [ "Sandboxes" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "default_template", "templates" ], "properties": { "available": { "type": "boolean" }, "default_template": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object" } }, "reason": { "type": "string" } } } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Availability requires an immutable qualified image and enabled capacity. CPU support is gated until qualification." } }, "/v1/sandboxes/capabilities": { "get": { "operationId": "sandboxCapabilities", "summary": "Read sandbox environment capabilities", "tags": [ "Sandboxes" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "default_template", "templates" ], "properties": { "available": { "type": "boolean" }, "default_template": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object" } }, "reason": { "type": "string" } } } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/sandboxes/{id}/sleep": { "post": { "operationId": "sleepSandbox", "summary": "Sleep a sandbox", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } }, "description": "Saved project deletion is separate from compute termination. Sleep refuses active commands and retains original limits." } }, "/v1/sandboxes/{id}/wake": { "post": { "operationId": "wakeSandbox", "summary": "Wake a sandbox", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sandbox" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } }, "description": "Saved project deletion is separate from compute termination. Sleep refuses active commands and retains original limits." } }, "/v1/sandboxes/{id}/files": { "post": { "operationId": "sandboxFiles", "summary": "Operate on saved project files", "tags": [ "Sandboxes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxExec" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxFileOperation" } } } }, "description": "Returns a fenced command receipt. Read its verified JSON output through the execution stream. Reads use chunks up to 256 KiB and writes use chunks up to 32 KiB. Existing file writes require the current SHA-256." } }, "/v1/agents": { "post": { "operationId": "createManagedAgent", "summary": "Deploy a managed Python agent", "tags": [ "Managed agents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgent" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentCreate" } } } }, "description": "Admission is limited to explicitly enabled accounts. Immutable revisions preserve the accepted code for existing runs. Worker concurrency includes unresolved cleanup liability." }, "get": { "operationId": "listManagedAgents", "summary": "List agent deployments", "tags": [ "Managed agents" ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgent" } }, "next_after": { "type": "string" } }, "required": [] } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/agents/{id}": { "get": { "operationId": "getManagedAgent", "summary": "Read an agent deployment", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgent" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } }, "patch": { "operationId": "updateManagedAgent", "summary": "Create an immutable agent revision", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgent" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentUpdate" } } } } } }, "/v1/agents/{id}/pause": { "post": { "operationId": "pauseManagedAgent", "summary": "Pause an agent deployment", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgent" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/v1/agents/{id}/resume": { "post": { "operationId": "resumeManagedAgent", "summary": "Resume an agent deployment", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgent" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/v1/agents/{id}/observations": { "get": { "operationId": "getManagedAgentObservations", "summary": "Observe retained lifecycle evidence and resource liability", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentObservations" } } } }, "404": { "description": "The agent definition does not exist or is not owned by the authenticated tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Requires authentication and an agent definition owned by the authenticated tenant. Returns 404 when the definition does not exist or belongs to another tenant. Returns one read-only database snapshot with a paginated run projection. Counts cover all runs of the definition. Missing timestamps and productive activity remain explicitly unmeasured. Available for retained work when new admission is disabled." } }, "/v1/agents/{id}/runs": { "post": { "operationId": "submitManagedRun", "summary": "Accept durable work before provisioning", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRun" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentSubmit" } } } }, "description": "Reuse the same idempotency key and input after an uncertain response. A session key serializes stateful work. Missing session keys create independent state." }, "get": { "operationId": "listManagedRuns", "summary": "List accepted managed work", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Pass next_after from the preceding page with the same order. With order=newest, the cursor must identify a retained run owned by this agent and account." }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "newest" ] }, "description": "Use newest for descending submission time with descending run IDs breaking ties. Omitting order preserves ascending run ID pagination." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRun" } }, "next_after": { "type": "string" } }, "required": [] } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/agents/{id}/runs/{run_id}/answer": { "get": { "operationId": "getManagedRunAnswer", "summary": "Read the complete saved assistant answer", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete saved answer text.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Returns the complete text from an owned run result, including an answer stored outside the inline preview. The result must remain within its retention period. This read never executes the model again." } }, "/v1/agents/{id}/runs/{run_id}": { "get": { "operationId": "getManagedRun", "summary": "Read progress, waiting and recovery", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRun" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/agents/{id}/runs/{run_id}/signals": { "post": { "operationId": "signalManagedRun", "summary": "Deliver a durable signal", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRun" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentSignal" } } } } } }, "/v1/agents/{id}/runs/{run_id}/cancel": { "post": { "operationId": "cancelManagedRun", "summary": "Revoke execution and continue cleanup", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRun" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/v1/agents/{id}/runs/{run_id}/steps": { "get": { "operationId": "listManagedAgentSteps", "summary": "Read a page of durable step metadata", "description": "Unknown external effects block the run until explicitly resolved using independent evidence.", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } }, { "name": "after", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStepPage" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/agents/{id}/runs/{run_id}/resolve": { "post": { "operationId": "resolveManagedAgentStep", "summary": "Resolve an independently verified unknown effect", "description": "Compare-and-swap requires the current unknown step revision and an evidence digest. completed requires the verified JSON result. no_effect authorizes one further bounded attempt. cancelled stops the run. Original unknown attempts remain retained.", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9:_.-]{1,128}$", "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReceipt" } } } }, "default": { "description": "Operation refused. Unavailable capability is reported while durable agents are disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResolution" } } } } } }, "/v1/agents/{id}/runs/{run_id}/retry": { "post": { "operationId": "retryManagedRun", "summary": "Retry blocked work after verified cleanup", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRun" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Retains the accepted revision, spending policy and external-effect history. Unknown effects require explicit reconciliation before retry." } }, "/v1/agents/{id}/revisions/{revision}": { "get": { "operationId": "getManagedAgentRevision", "summary": "Read an immutable accepted code revision", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentRevision" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/agents/{id}/revisions": { "get": { "operationId": "listManagedAgentRevisions", "summary": "List immutable deployment revisions", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRevision" } }, "next_after": { "type": "string" } }, "required": [ "revisions", "next_after" ] } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } } } }, "/v1/cloud-onboarding-sessions": { "post": { "operationId": "startCloudOnboarding", "summary": "Start or replay guided cloud setup", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Creates setup intent only. Requires configured guided deployment settings for the selected provider. Same normalized settings and key return the same session without extending expiry. Changed settings or more than five active sessions return 409 cloud_onboarding_conflict. Missing deployment settings return 503 cloud_setup_unavailable. No observation connection is created until verification succeeds.", "responses": { "201": { "description": "Start or replay guided cloud setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingResponse" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable key for this setup, at most 200 UTF-8 bytes with no control characters. Reuse after an uncertain response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingInput" } } } } }, "get": { "operationId": "listCloudOnboardingSessions", "summary": "List active guided cloud setup sessions", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Returns only pending, unexpired sessions in creation order. Completed, cancelled, and expired sessions remain available by ID.", "responses": { "200": { "description": "List active guided cloud setup sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingSessionList" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-onboarding-sessions/{id}": { "get": { "operationId": "getCloudOnboardingSession", "summary": "Resume guided cloud setup", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Returns the saved session and next action, including terminal and expired records. Reading does not renew expiry.", "responses": { "200": { "description": "Resume guided cloud setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingResponse" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." } ] } }, "/v1/cloud-onboarding-sessions/{id}/verify": { "post": { "operationId": "verifyCloudOnboarding", "summary": "Verify cloud access and complete setup", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. For AWS, derives the exact role from the saved session and submitted account ID. For pending sessions, STS must reject missing and incorrect external IDs, then assume the role and report the expected account, role, and session identity. For Google Cloud, verifies the saved project ID and submitted project number through the approved observer identity, then checks inventory, resource discovery and monitoring reads. A return URL, account ID or project number alone cannot complete setup. Verification has a 25-second deadline and bounded concurrency. Failed access returns 422 cloud_access_unverified, expired pending setup returns 410 cloud_onboarding_expired, and rate limits return 429 cloud_busy. Completion rechecks administrator access, revision, state, and expiry atomically. Concurrent completion and retries for the same verified account return one connection. Billing export access is optional and checked during collection. Completed retries do not reconnect disconnected access.", "responses": { "200": { "description": "Verify cloud access and complete setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingResponse" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingVerifyRequest" } } } } } }, "/v1/cloud-onboarding-sessions/{id}/cancel": { "post": { "operationId": "cancelCloudOnboarding", "summary": "Cancel pending guided cloud setup", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Cancels pending setup and fences later verification. Retrying cancellation is safe. A completed setup returns a conflict. This does not delete a customer-created AWS stack or disconnect an existing connection.", "responses": { "200": { "description": "Cancel pending guided cloud setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudOnboardingResponse" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." } ] } }, "/v1/cloud-onboarding/aws/template": { "get": { "operationId": "getAWSObservationTemplate", "summary": "Download the static AWS observation template", "tags": [ "Cloud observation" ], "security": [], "description": "Public, credential-free CloudFormation JSON that creates one IAM observation role. It provisions no compute, storage, or networking. Operators must publish this versioned template to an S3 object accessible to customer CloudFormation setup and configure NODUS_CLOUD_AWS_TEMPLATE_URL. This download endpoint itself is not the S3 template URL.", "responses": { "200": { "description": "IAM-only CloudFormation template", "content": { "application/json": { "schema": { "type": "object", "required": [ "AWSTemplateFormatVersion", "Parameters", "Resources", "Outputs" ], "additionalProperties": true } } } } } } }, "/v1/cloud-connections": { "get": { "operationId": "listCloudConnections", "summary": "List cloud observation connections", "tags": [ "Cloud observation" ], "description": "Returns the authenticated team's connections excluding disconnected records. Credentials are never returned. Reading does not require administrator access or a paid pool subscription.", "responses": { "200": { "description": "List cloud observation connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudConnectionList" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-connections/setup": { "get": { "operationId": "getCloudConnectionSetup", "summary": "Get cloud setup availability and AWS trust settings", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Returns the principal ARN, tenant external ID, guided AWS availability, and observation capabilities. Availability checks deployment settings, not live AWS permissions.", "responses": { "200": { "description": "Get cloud setup availability and AWS trust settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudConnectionSetup" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-connections/{id}": { "get": { "operationId": "getCloudConnectionReport", "summary": "Read observed cloud resources, usage, and spending", "tags": [ "Cloud observation" ], "description": "Returns one connected account, project, or subscription and its report. Sources retain independent collection states. Unknown measurements remain unavailable. Provider-reported spending and currencies remain separate from Nodus billing. Invalid report windows return 400 invalid_window. Disconnected records return 404.", "responses": { "200": { "description": "Read observed cloud resources, usage, and spending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudConnectionReportResponse" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 30 }, "description": "Measured history window in days." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 30 }, "description": "Usage-continuation forecast horizon in days." } ] }, "delete": { "operationId": "disconnectCloudConnection", "summary": "Disconnect cloud observation", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Deletes the stored credential and fences collection results. Retains historical snapshots without exposing them through these routes. Does not revoke the cloud role, delete its CloudFormation stack, or terminate customer resources. An already disconnected or missing connection returns 404. Disables future execution routing for its associated pool while retaining active workloads, host credentials and exact cleanup authority.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." } ], "responses": { "204": { "description": "Disconnected" }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-connections/{id}/refresh": { "post": { "operationId": "refreshCloudConnection", "summary": "Request cloud observation collection", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Queues collection when no current collection lease is active and at least ten minutes have passed since the previous attempt. A conflicting request returns 409 cloud_conflict. The regular collection interval is one hour.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned session or connection identity." } ], "responses": { "202": { "description": "Collection queued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ] } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-connections/{id}/execution": { "get": { "operationId": "getCloudExecution", "summary": "Read cloud execution setup", "tags": [ "Cloud observation" ], "description": "Returns explicit execution authorization and administrator-declared host associations. A read-only cloud connection starts disabled without an execution pool. This response does not establish host readiness. Unavailable deployments and disconnected or foreign connections return 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned Nodus cloud connection identity." } ], "responses": { "200": { "description": "Read cloud execution setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudExecution" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setCloudExecution", "summary": "Enable or pause execution on existing AWS or Google Cloud capacity", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. The console uses the same service with its authenticated session. Enabling creates or reuses one dedicated Nodus pool for this AWS or Google Cloud connection with free private routing and prediction. It does not create or start cloud instances, install software, enroll a host, grant a host execution credentials or authorize paid overflow. Submit through the existing workload API with placement.pool set to the returned pool_id. Disabling blocks new routing while retaining current workload ownership and cleanup. Retries reuse the same pool. Missing enabled returns 400. Execution setup supports AWS and Google Cloud.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned Nodus cloud connection identity." } ], "responses": { "200": { "description": "Enable or pause execution on existing AWS or Google Cloud capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudExecution" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudExecutionUpdate" } } } } } }, "/v1/cloud-connections/{id}/execution/hosts": { "post": { "operationId": "associateCloudExecutionHost", "summary": "Associate an enrolled host with observed AWS or Google Cloud capacity", "tags": [ "Cloud observation" ], "description": "Requires an API key owned by a user who is currently a team administrator. The console uses the same service with its authenticated session. Requires execution setup to be enabled and the Nodus host to belong to its dedicated pool. Checks the exact running GPU instance and region against ready account or project inventory collected within the last two hours. Google Cloud requires zone and matches its server-generated numeric instance ID in the connected project. The administrator declares where the host was installed. This does not attest physical host identity or enable execution credentials. Existing associations are immutable, with exact retries returning the same record. Missing hosts return 404. Unavailable inventory and conflicting associations return 409.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant-owned Nodus cloud connection identity." } ], "responses": { "200": { "description": "Associate an enrolled host with observed AWS or Google Cloud capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudExecutionHost" } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudExecutionHostInput" } } } } } }, "/v1/cloud-google-authorizations": { "post": { "operationId": "startGoogleCloudAuthorization", "summary": "Start Google Cloud sign-in", "tags": [ "Cloud observation" ], "description": "Requires a current team administrator. This browser consent flow is completed by the hosted Nodus console. It creates a one-time state and PKCE challenge. The console opens authorization_url in a new window and Google redirects to /clouds/google/callback/ on the configured Nodus console origin. The callback sends state and code only to that same-origin console through postMessage or BroadcastChannel. The console verifies the pending state and calls the authorize endpoint as the same administrator. Keep the console tab open during consent. External applications and CLI clients cannot supply a custom callback URL or receive these credentials. Direct customers to the Compute page at https://console.nodus-compute.ai/console/?view=compute to connect, then list their cloud connections through the API. Requests online cloud-platform access for temporary project setup. No offline refresh token is requested.", "responses": { "201": { "description": "Start Google Cloud sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleCloudAuthorizationResponse" } } } }, "default": { "description": "Stable Nodus error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cloud-google-authorizations/{id}/authorize": { "post": { "operationId": "authorizeGoogleCloudConnection", "summary": "Complete Google consent", "tags": [ "Cloud observation" ], "description": "Called by the hosted Nodus console after its /clouds/google/callback/ page returns state and code through the same-origin browser handoff described by startGoogleCloudAuthorization. Requires the same current team administrator who started consent. Exchanges the one-use code with server-held PKCE. State, current administrator and tenant must match the starting authorization. Replays are rejected. The temporary administrator token is encrypted and never returned.", "responses": { "200": { "description": "Complete Google consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleCloudAuthorizationResponse" } } } }, "default": { "description": "Stable Nodus error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "minLength": 32, "maxLength": 256 }, "code": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "state", "code" ] } } } } } }, "/v1/cloud-google-authorizations/{id}/projects": { "get": { "operationId": "listGoogleCloudProjects", "summary": "List projects available for connection", "tags": [ "Cloud observation" ], "description": "Requires the same current team administrator who started consent. Returns up to 100 visible active projects and a continuation token. A selected or completed setup returns its authorization without rediscovering projects.", "responses": { "200": { "description": "List projects available for connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleCloudAuthorizationResponse" } } } }, "default": { "description": "Stable Nodus error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "schema": { "type": "string", "maxLength": 4096 } } ] } }, "/v1/cloud-google-authorizations/{id}/connect": { "post": { "operationId": "connectGoogleCloudProject", "summary": "Advance Google Cloud project setup", "tags": [ "Cloud observation" ], "description": "Requires the same current team administrator who started consent. Binds one project and optional billing location, then advances one resumable setup stage per call. Repeat the identical selection while the response is 202. Existing IAM policies and session ownership are preserved. Billing preparation is optional and can be skipped. Completion requires verified read-only access and returns 200 with the observation connection. Completion erases the temporary administrator token and queues collection. No compute is created.", "responses": { "202": { "description": "Advance Google Cloud project setup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleCloudAuthorizationResponse" } } } }, "default": { "description": "Stable Nodus error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Verified connection completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleCloudAuthorizationResponse" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "project_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{4,28}[a-z0-9]$" }, "billing_location": { "type": "string", "enum": [ "", "US", "EU" ] }, "skip_billing": { "type": "boolean" } }, "required": [ "project_id" ] } } } } } }, "/v1/cloud-google-authorizations/{id}": { "delete": { "operationId": "cancelGoogleCloudAuthorization", "summary": "Cancel Google Cloud sign-in or setup", "tags": [ "Cloud observation" ], "description": "Requires the same current team administrator who started consent. Erases the temporary credential and fences in-flight completion. Already-created Google access resources remain in place. Completed connections are disconnected using the cloud connection route.", "responses": { "204": { "description": "Cancel Google Cloud sign-in or setup" }, "default": { "description": "Stable Nodus error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/cloud-connections/overview": { "get": { "operationId": "getCloudOverview", "summary": "Read aggregate connected-cloud spend and compute", "tags": [ "Cloud observation" ], "description": "Aggregates the tenant’s connected accounts and projects. Google legacy whole-export rows are restricted to connected projects. Currencies remain separate, missing days remain unknown, and forecasts require fresh data from every connected scope. Azure onboarding is coming soon.", "responses": { "200": { "description": "Aggregate observation across connected scopes", "content": { "application/json": { "schema": { "type": "object", "required": [ "report", "connection_count" ], "properties": { "report": { "$ref": "#/components/schemas/CloudObservationReport" }, "connection_count": { "type": "integer", "minimum": 0 } } } } } }, "default": { "description": "Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 30 }, "description": "Measured history window in days." }, { "name": "horizon", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 30 }, "description": "Usage-continuation forecast horizon in days." } ] } }, "/v1/agents/{id}/groups": { "get": { "operationId": "listManagedAgentGroups", "summary": "Discover retained groups for an agent definition", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Group ID from next_after. Must belong to the same tenant and agent definition." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Retained groups in descending creation order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentGroup" } }, "next_after": { "type": "string", "description": "Use as after for the next page. Empty when no older groups remain." } }, "required": [ "groups", "next_after" ] } } } }, "404": { "description": "Definition or cursor is missing or not owned by this tenant and definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Accepts API-key and console-session authentication. Returns retained active and cancelled groups for the owned definition, including while new admission is disabled. Groups are ordered by creation time descending, then group ID descending. Each page is a consistent read-only snapshot. Newer groups are discovered by restarting from the first page. Listing does not grant admission entitlement, increase execution limits or reserve spending." } }, "/v1/agent-groups": { "post": { "operationId": "createManagedAgentGroup", "summary": "Create a bounded group on one agent definition", "tags": [ "Managed agents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroup" } } } }, "404": { "description": "Group or definition is missing or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroupCreate" } } } }, "description": "Requires explicit group admission entitlement and an owned agent definition. Pins one definition revision. The same submission key and body recover the same group after an uncertain response, including when new admission is disabled. Group limits cannot raise the deployment worker or spending limit." } }, "/v1/agent-groups/{id}": { "get": { "operationId": "getManagedAgentGroup", "summary": "Observe group progress and outstanding allocation liability", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroup" } } } }, "404": { "description": "Group or definition is missing or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Requires authentication and a group owned by the authenticated tenant. A missing or foreign-owned group returns 404. Returns one database snapshot of task counts, retained payload counts, recorded spending and unsettled allocations. Available when new admission is disabled." } }, "/v1/agent-groups/{id}/runs": { "post": { "operationId": "submitManagedAgentGroupBatch", "summary": "Atomically submit up to 100 independent or dependent tasks", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroupBatch" } } } }, "404": { "description": "Group or definition is missing or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroupBatchRequest" } } } }, "description": "Requires authentication and a group owned by the authenticated tenant. A missing or foreign-owned group returns 404. The whole request is limited to 1 MiB. Duplicate task keys, missing dependencies and cycles are rejected atomically. A task key with changed input, dependencies or deadline conflicts. Retrying the same batch key returns its original ordered receipt even after cancellation or admission disablement. Separate tasks have independent sessions and writable state." }, "get": { "operationId": "listManagedAgentGroupRuns", "summary": "List retained tasks with stable pagination", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAgentRun" } }, "next_after": { "type": "string" } }, "required": [ "runs", "next_after" ] } } } }, "404": { "description": "Group or definition is missing or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Requires authentication and a group owned by the authenticated tenant. A missing or foreign-owned group returns 404. Returns existing managed-run projections ordered by run ID. Pass next_after as after and stop at an empty cursor. Cursor ownership is checked. Each page is a separate database snapshot." } }, "/v1/agent-groups/{id}/cancel": { "post": { "operationId": "cancelManagedAgentGroup", "summary": "Fence new group work and continue member cleanup", "tags": [ "Managed agents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Stable key for this logical operation. Reuse the same key and body after an uncertain response." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAgentGroup" } } } }, "404": { "description": "Group or definition is missing or belongs to another tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } }, "default": { "description": "Operation refused with a diagnostic and next action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxError" } } } } }, "description": "Requires authentication and a group owned by the authenticated tenant. A missing or foreign-owned group returns 404. Commits a durable cancellation fence. Existing executors asynchronously cancel nonterminal members and reconcile their allocations, including when new admission is disabled. The 202 response does not claim completed physical cleanup. Previously completed results are retained." } } }, "security": [ { "ApiKey": [] } ], "servers": [ { "url": "/", "description": "Set this to your deployment API origin (the same NODUS_BASE_URL used by the SDK)." } ], "tags": [ { "name": "Workloads" }, { "name": "Webhooks" }, { "name": "Assets" }, { "name": "Sandboxes" }, { "name": "Managed models", "description": "Account-qualified text and function-tool model access billed to Nodus credits." }, { "name": "Workspaces", "description": "Named file persistence with one live sandbox writer." }, { "name": "Research workspaces", "description": "Saved GPU research projects with replaceable compute, browser VS Code, JupyterLab and desktop SSH. Availability requires an enabled deployment and qualified runtime configuration." }, { "name": "Pools" }, { "name": "Operations" }, { "name": "Cloud observation", "description": "Read-only cloud inventory, usage, spending, and guided AWS setup. Connecting does not enroll execution capacity." } ], "x-source-revision": "fd919e576d7300722d687111625114383475fcf4" }