{ "components": { "schemas": { "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": { "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" }, "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." } }, "x-go-source": "internal/store/assets.go", "x-go-type": "Asset" }, "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." } }, "x-go-source": "internal/assets/import.go", "x-go-type": "Request", "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" }, "billing_enabled": { "type": "boolean", "const": false } }, "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" }, "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 } }, "x-go-source": "internal/benchmark/benchmark.go", "x-go-type": "Matrix" }, "BenchmarkReport": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "budget_usd": { "type": "number" }, "spend_usd": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkCell" } } }, "x-go-source": "internal/benchmark/benchmark.go", "x-go-type": "Report" }, "BenchmarkRequest": { "type": "object", "additionalProperties": false, "required": [ "workload", "matrix", "budget_usd" ], "properties": { "workload": { "$ref": "#/components/schemas/WorkloadPayload" }, "matrix": { "$ref": "#/components/schemas/BenchmarkMatrix" }, "budget_usd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000, "description": "One total USD cap. Server divides microdollars across at most 64 immutable cell budgets. Unused cell allocations are not redistributed." } }, "x-go-source": "internal/benchmark/benchmark.go", "x-go-type": "Request" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "CheckpointSummary" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "Continuity" }, "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" } }, "x-go-source": "internal/models/models.go", "x-go-type": "CostBreakdown" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "CustomerFallbackBranch" }, "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" } }, "x-go-source": "internal/store/pilot.go", "x-go-type": "CustomerLedgerEntry" }, "CustomerRejectedOffer": { "type": "object", "properties": { "reason": { "type": "string" } }, "x-go-source": "internal/models/models.go", "x-go-type": "CustomerRejectedOffer" }, "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" } } }, "x-go-source": "internal/models/models.go", "x-go-type": "CustomerRouteSummary" }, "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": { "type": "object", "required": [ "id", "stage_id", "generation", "text" ], "properties": { "id": { "type": "integer" }, "stage_id": { "type": "string" }, "generation": { "type": "integer" }, "text": { "type": "string" } } } }, "next_cursor": { "type": "string" }, "truncated": { "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" }, "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." }, "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." } }, "x-go-source": "internal/store/meter.go", "x-go-type": "Meter" }, "Outcome": { "type": "object", "properties": { "max_cost_usd": { "type": "number", "description": "Hard customer spending limit in USD for this workload. Omitted means no per-run limit. Available credits and configured account limits still apply. Acceptance does not guarantee completion within the limit." }, "complete_by": { "type": "string", "description": "RFC3339 completion deadline, or empty/omitted for none. Example: 2026-12-01T18:00:00Z." } }, "x-go-source": "internal/models/models.go", "x-go-type": "Outcome" }, "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" } }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "Policy" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "Requirements" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "ResourceAttributes" }, "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": { "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" } }, "x-go-source": "internal/store/route_insights.go", "x-go-type": "RoutingPlacement" }, "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." }, "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." } } }, "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": "Optional shell setup command recorded as an ordinary sandbox execution. Failure leaves the sandbox usable with a bootstrap_failed warning." }, "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 under its existing budget and 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." } }, "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 under its existing budget and 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", "exclusiveMinimum": 0, "description": "Hard customer spending limit for this sandbox. The server default is 5 USD. Reconnecting without a budget preserves the existing limit. Account credits and configured account limits also apply." }, "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", "x-go-source": "internal/sandbox/service.go", "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." } }, "x-go-type": "Service" }, "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" } }, "x-go-source": "internal/models/models.go", "x-go-type": "ScoreBreakdown" }, "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." } }, "x-go-source": "internal/store/sandbox_secrets.go", "x-go-type": "SecretMetadata" }, "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" } }, "x-go-source": "internal/models/models.go", "x-go-type": "StageInput" }, "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" ], "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/OutputDeclaration" } ] }, "description": "Named output paths or file and database sink declarations. 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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "StagePayload", "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "StageRunSummary" }, "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." } }, "x-go-source": "internal/models/unit_metrics.go", "x-go-type": "UnitMetrics" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "Workload" }, "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" } }, "x-go-source": "internal/models/models.go", "x-go-type": "WorkloadEvent" }, "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" } }, "x-go-source": "internal/models/models.go", "x-go-type": "WorkloadInput", "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." } }, "x-go-source": "internal/store/pilot.go", "x-go-type": "WorkloadListItem" }, "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." } }, "x-go-source": "internal/models/models.go", "x-go-type": "WorkloadPayload", "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})?$" } }, "x-go-source": "internal/models/models.go", "x-go-type": "WorkloadSource" }, "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" }, "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" ] } } }, "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 funded 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" } }, "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 free read-only measurement, optional account-priced Predict, and explicit paid Route activation. Each execution host requires separate host-bound reenrollment. Owned cost is advisory and does not create a charge.", "x-go-source": "internal/models/pools.go", "x-go-type": "PrivatePool" }, "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, "x-go-source": "internal/api/pools.go", "x-go-type": "poolCreateRequest" }, "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": "Explicit route-platform-v1 consent required on each enable request." }, "accepted_route_rate_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 9223372036854775807, "description": "Explicit 20000 USD micros per active customer device-hour required on each enable request." }, "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 funded 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, "x-go-source": "internal/api/pools.go", "x-go-type": "poolPatchRequest", "description": "Change Predict separately from other settings. Enabling requires explicit accepted_predict_rate_version predict-account-monthly-v1 and accepted_predict_monthly_micros 99000000. Disabling requires only predict_enabled false and stops future refresh and renewal after the last enabled pool is disabled. Cached views remain readable. Change Route and its waiting settings separately from Predict, name, and owned cost. Enabling Route requires an active pool and explicit route-platform-v1 consent at 20000 USD micros per active customer device-hour, including optimize and apply. 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, "x-go-source": "internal/api/pools.go", "x-go-type": "poolTokenRequest", "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" ], "x-go-source": "internal/store/pools.go", "x-go-type": "PoolEnrollmentToken" }, "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" ], "x-go-source": "internal/models/pools.go", "x-go-type": "HostDevice" }, "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" ], "x-go-source": "internal/models/pools.go", "x-go-type": "PoolHost" }, "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" ], "x-go-source": "internal/finops/ledger.go", "x-go-type": "Metrics", "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" ], "x-go-source": "internal/api/pools_utilization.go", "x-go-type": "poolUtilizationBucket", "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" ], "x-go-source": "internal/api/pools_utilization.go", "x-go-type": "poolUtilizationHost" }, "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" ], "x-go-source": "internal/api/pools_utilization.go", "x-go-type": "poolUtilizationResponse" }, "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" ], "x-go-source": "internal/store/pools_predict_billing.go", "x-go-type": "PoolPredictSubscription", "description": "Fixed USD 99 per account per UTC calendar month, independent of device and pool count. The first activation charges the full current month. paid_current_period means funded by credits or accepted postpaid receivable, not that a postpaid invoice has been paid." }, "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" ], "x-go-source": "internal/finops/forecast.go", "x-go-type": "Band" }, "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" ], "x-go-source": "internal/finops/forecast.go", "x-go-type": "Forecast", "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" ], "x-go-source": "internal/finops/forecast.go", "x-go-type": "ForecastEvaluation", "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" ], "x-go-source": "internal/store/pools_predict.go", "x-go-type": "PoolAdvisoryPrice", "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" ], "x-go-source": "internal/store/pools_predict.go", "x-go-type": "PoolForecastSnapshot" }, "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" ], "x-go-source": "internal/store/pools_predict.go", "x-go-type": "PoolRecommendationOutcome", "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" ], "x-go-source": "internal/store/pools_predict.go", "x-go-type": "PoolRecommendationDone", "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" ], "x-go-source": "internal/store/pools_predict.go", "x-go-type": "PoolRecommendation" }, "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" ], "x-go-source": "internal/api/pools_predict.go", "x-go-type": "poolForecastResponse" }, "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" ], "x-go-source": "internal/api/pools_predict.go", "x-go-type": "poolRecommendationsResponse", "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" ], "x-go-source": "internal/finops/optimize.go", "x-go-type": "Recommendation" }, "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" ], "x-go-source": "internal/finops/optimize.go", "x-go-type": "RightSizeEvidence", "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" ], "x-go-source": "internal/finops/optimize.go", "x-go-type": "DemandMass" }, "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" ], "x-go-source": "internal/finops/idle.go", "x-go-type": "IdleRecommendation", "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" ], "x-go-source": "internal/finops/idle.go", "x-go-type": "IdleReclaimEvidence" }, "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" ], "x-go-source": "internal/finops/drain.go", "x-go-type": "DrainRecommendation", "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" ], "x-go-source": "internal/finops/drain.go", "x-go-type": "DrainWindowEvidence" }, "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" ], "x-go-source": "internal/finops/defragment.go", "x-go-type": "DefragmentEvidence" }, "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" ], "x-go-source": "internal/finops/defragment.go", "x-go-type": "DefragmentRecommendation", "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.", "x-go-source": "internal/models/placement.go", "x-go-type": "Placement" }, "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 } }, "x-go-source": "internal/api/pools_action_policies.go", "x-go-type": "poolActionPolicyRequest", "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." } }, "x-go-source": "internal/api/pools_action_policies.go", "x-go-type": "poolActionPolicyView" }, "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" } } }, "x-go-source": "internal/api/pools_action_policies.go", "x-go-type": "poolActionSettingsResponse" }, "PoolActKillSwitchRequest": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "x-go-source": "internal/api/pools_action_policies.go", "x-go-type": "poolActKillSwitchRequest", "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." } }, "x-go-source": "internal/store/pools_action_views.go", "x-go-type": "PoolShadowView", "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 } }, "x-go-source": "internal/store/pools_action_views.go", "x-go-type": "PoolShadowPage" }, "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." } }, "x-go-source": "internal/api/pools_action_proposals.go", "x-go-type": "poolActOutcomeView", "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" } ] } }, "x-go-source": "internal/api/pools_action_proposals.go", "x-go-type": "poolActProposalView" }, "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 } }, "x-go-source": "internal/api/pools_action_proposals.go", "x-go-type": "poolActProposalsResponse" }, "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" ], "x-go-source": "internal/store/workload_freeze.go", "x-go-type": "WorkloadFreeze", "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" ], "x-go-source": "internal/finops/wait_tuning.go", "x-go-type": "WaitTuningEvidence" }, "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" ], "x-go-source": "internal/finops/wait_tuning.go", "x-go-type": "WaitTuningRecommendation", "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" ], "x-go-source": "internal/finops/queue.go", "x-go-type": "QueueEvidence", "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." } }, "x-go-source": "internal/models/assets.go", "x-go-type": "BucketInput" }, "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." }, "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.", "x-go-source": "internal/models/rl.go", "x-go-type": "RLMetadata" }, "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." } }, "x-go-source": "internal/store/rl_grading_results.go", "x-go-type": "RLGradingResults" }, "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." } }, "x-go-source": "internal/protocol/rl_grading.go", "x-go-type": "RLGradingResponse" }, "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.", "x-go-source": "internal/models/rl.go", "x-go-type": "RLEvent" }, "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.", "x-go-source": "internal/store/rl_events.go", "x-go-type": "RLEventRow" }, "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.", "x-go-source": "internal/store/rl_events.go", "x-go-type": "RLEventPage" }, "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" ], "x-go-source": "internal/models/rl.go", "x-go-type": "RLRecipeProvenance" }, "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", "minimum": 1, "maximum": 100, "default": 5, "description": "Run spending limit. This is not a prediction of completion cost." }, "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": [], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "Request", "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", "minimum": 1, "maximum": 100, "default": 5, "description": "Run spending limit. This is not a prediction of completion cost." }, "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" ], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "Output" }, "RLRecipePhase": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "enum": [ "baseline", "training", "evaluation", "export" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "label", "description" ], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "Phase" }, "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", "minimum": 1, "maximum": 100, "default": 5, "description": "Run spending limit. This is not a prediction of completion cost." }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 42 } }, "required": [ "evaluation_tasks", "training_steps", "max_cost_usd", "seed" ], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "DefaultValues" }, "RLRecipeLimits": { "type": "object", "additionalProperties": false, "properties": { "evaluation_tasks_min": { "type": "integer" }, "evaluation_tasks_max": { "type": "integer" }, "training_steps_min": { "type": "integer" }, "training_steps_max": { "type": "integer" } }, "required": [ "evaluation_tasks_min", "evaluation_tasks_max", "training_steps_min", "training_steps_max" ], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "Limits" }, "RLRecipeDescriptor": { "type": "object", "additionalProperties": false, "properties": { "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": [ "id", "version", "environment_id", "name", "model", "model_revision", "taskset", "modes", "available", "defaults", "limits", "outputs" ], "x-go-source": "internal/rlrecipe/recipe.go", "x-go-type": "Descriptor" }, "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" ], "x-go-source": "internal/api/estimates.go", "x-go-type": "EstimatePreview" }, "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" ], "x-go-source": "internal/api/rl_runs.go", "x-go-type": "rlRunPreview" }, "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." } }, "x-go-source": "internal/connections/connections.go", "x-go-type": "CreateRequest" }, "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" } }, "x-go-source": "internal/connections/connections.go", "x-go-type": "Connection" }, "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." } }, "x-go-source": "internal/store/connection_exports.go", "x-go-type": "ConnectionExport" }, "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" ], "x-go-package": "internal/models", "x-go-type": "WorkloadLink" }, "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" } }, "x-go-source": "internal/store/connection_loads.go", "x-go-type": "ConnectionLoad" }, "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" } }, "x-go-source": "internal/models/checkpoint_integration.go", "x-go-type": "CheckpointPreparationSummary" }, "OperationDefinition": { "type": "object", "x-go-source": "internal/operations/operations.go", "x-go-type": "Definition", "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 with explicit outcome.max_cost_usd. Preserve the user's command, image, resources and budget.", "properties": { "outcome": { "properties": { "max_cost_usd": { "exclusiveMinimum": 0, "type": "number" } }, "required": [ "max_cost_usd" ], "type": "object" } }, "required": [ "outcome" ], "type": "object" } }, "required": [ "workload" ], "type": "object" }, "OperationWorkloadsSubmitArguments": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 256, "minLength": 1, "pattern": "^[^\\r\\n]+$", "type": "string" }, "workload": { "description": "Customer HTTP workload request with explicit outcome.max_cost_usd. Preserve the user's command, image, resources and budget.", "properties": { "outcome": { "properties": { "max_cost_usd": { "exclusiveMinimum": 0, "type": "number" } }, "required": [ "max_cost_usd" ], "type": "object" } }, "required": [ "outcome" ], "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" } ] }, "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": 9, "minProperties": 1, "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" } ] }, "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": [ { "exclusiveMinimum": 0, "maximum": 100000, "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" } ] } }, "type": "object" } }, "required": [ "expected_revision", "patch" ], "type": "object" }, "RunDraftValues": { "type": "object", "maxProperties": 9, "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": { "exclusiveMinimum": 0, "maximum": 100000, "type": "number" }, "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" } } }, "RunDraft": { "type": "object", "x-go-source": "internal/rundraft/draft.go", "x-go-type": "Draft", "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" } } } }, "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, asset, and webhook 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. Imports and uploads complete synchronously. 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 from GET /v1/assets first. Imports and uploads have no idempotency contract. After a timeout, 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." } ], "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. A payment method, account headroom, and the sandbox budget are enforced 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 budget, 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 budget_exceeded means available credits or a configured spending limit prevent 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." } } }, "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." } ], "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." } }, "/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." } ], "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" } } } }, "/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." } ], "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/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", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspaces" ], "properties": { "workspaces": { "type": "array", "items": { "$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" } } } } } } }, "/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 funded 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, funded Predict, active Route consent 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 funded 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 funded 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-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-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. Requires an explicit positive outcome.max_cost_usd. 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 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 an explicit positive outcome.max_cost_usd and 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.", "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" ] }, "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" } ] } }, "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" ] } ] } } } }, "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" } } } } } } } }, "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": "Workspaces", "description": "Named file persistence with one live sandbox writer." }, { "name": "Pools" }, { "name": "Operations" } ], "x-source-revision": "fd919e576d7300722d687111625114383475fcf4" }