# API schema definitions Shared request and response definitions from the OpenAPI contract. These definitions are generated without changing the contract. Required fields, enums and numeric-string formats come from the OpenAPI source. [Download the complete specification](/openapi.json). ## UUID ```json { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "example": "3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40" } ``` ## Rfc3339Utc ```json { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$", "example": "2026-09-25T12:00:00Z" } ``` ## DecimalString ```json { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Unsigned base-10 integer as string; never a float.", "example": "1" } ``` ## MicroAmount ```json { "$ref": "#/components/schemas/DecimalString", "description": "Money in micro-units of the settlement asset as a base-10 integer string (\"5000000\" is 5 USDC). Never a float.", "example": "5000000" } ``` ## EvmAddress ```json { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x1111111111111111111111111111111111111111" } ``` ## Sha256Hash ```json { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "example": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } ``` ## ImageDigest ```json { "type": "string", "pattern": "^[^@\\s]+@sha256:[0-9a-f]{64}$", "example": "registry.amplerun.com/templates/pytorch-cuda@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } ``` ## ErrorEnvelope ```json { "type": "object", "additionalProperties": false, "required": [ "error" ], "example": { "error": { "code": "QUOTE_EXPIRED", "message": "quote expired", "retryable": false, "request_id": "3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40" } }, "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable", "request_id" ], "properties": { "code": { "type": "string", "minLength": 1, "description": "Stable machine-readable code (packages/contracts ERROR_CODES). Business routes use UNAUTHENTICATED (401), FORBIDDEN (403: missing scope, step-up or role), NOT_FOUND (404, also used where existence must not leak), INVALID_INPUT (422), ADMISSION_PAUSED and AUTHORIZATION_INVALID (403), IDEMPOTENCY_CONFLICT, CONFLICT, VERSION_CONFLICT, STALE_VERSION, STALE_FENCE, QUOTE_EXPIRED, INSUFFICIENT_FUNDS and STOP_IRREVERSIBLE (409), and UNAVAILABLE (503, or 429 when rate limited). The host-agent protocol adds BUDGET_VERSION_OLDER, BUDGET_FUNDING_MISMATCH, LEASE_SEQ_REPLAY, COMMAND_EXPIRED, UNSUPPORTED_PROTOCOL_VERSION and UNKNOWN_COMMAND_KIND. New codes may appear; handle an unknown code by its HTTP status." }, "message": { "type": "string", "minLength": 1, "description": "Human-readable; never contains secrets or stack traces." }, "retryable": { "type": "boolean", "description": "True when the identical request may succeed later: back off and retry with the same Idempotency-Key." }, "request_id": { "$ref": "#/components/schemas/UUID" } } } } } ``` ## CursorPage ```json { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ``` ## SettingView ```json { "type": "object", "additionalProperties": false, "required": [ "key", "category", "label", "help", "secret", "editable", "pinned_reason", "value", "source", "version", "updated_at", "updated_by", "env" ], "description": "One row of the D-20 settings registry, or a pinned root-of-trust key. When `secret` is true, `value` is always `{set: boolean}` — the wire never carries a secret or a root-of-trust value.", "properties": { "key": { "type": "string" }, "category": { "type": "string", "enum": [ "branding", "contact", "money", "mail", "alerts", "auth-providers", "chain-access", "operations" ] }, "label": { "type": "string" }, "help": { "type": "string" }, "secret": { "type": "boolean" }, "editable": { "type": "boolean", "description": "False for a root-of-trust key — refused at the API, read-only in the UI." }, "pinned_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": {}, "source": { "type": "string", "enum": [ "database", "environment", "default" ] }, "version": { "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "string" } } } ``` ## AvailabilityClass ```json { "type": "string", "enum": [ "dedicated", "interruptible" ], "description": "D-22. dedicated (the default) is never preempted. interruptible is sold only from idle or co-listed hosts: the host may take the machine back after preemption_notice_s seconds of notice, and billing stops at the notice." } ``` ## InterruptionEstimate ```json { "type": "object", "additionalProperties": false, "required": [ "runs", "uninterrupted", "horizon_h", "computed_at", "summary" ], "description": "D-22, interruptible offers only. Plain observed counts, never a prediction. A run is one continuous period in which the host reported the machine offerable (from heartbeats); it counts when it ended, or has already lasted horizon_h. uninterrupted is null below the sample gate (20 runs): not enough history.", "properties": { "runs": { "type": "integer", "minimum": 0, "description": "Most recent decided runs counted (at most 40)." }, "uninterrupted": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Of those runs, how many lasted horizon_h without interruption; null below the sample gate." }, "horizon_h": { "type": "integer", "minimum": 1 }, "computed_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "summary": { "type": "string", "description": "The counts in words, e.g. \"34 of the last 40 runs lasted 4 h without interruption\" or \"Not enough history (12 runs so far)\"." } } } ``` ## OfferSummary ```json { "type": "object", "additionalProperties": false, "required": [ "offer_id", "machine_id", "observed_at", "offer_version", "readiness", "total_rate_micro_per_hour", "included_quotas", "available_from", "available_until", "maintenance_windows", "expected_version" ], "properties": { "offer_id": { "$ref": "#/components/schemas/UUID" }, "machine_id": { "$ref": "#/components/schemas/UUID" }, "observed_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "offer_version": { "$ref": "#/components/schemas/DecimalString" }, "expected_version": { "$ref": "#/components/schemas/DecimalString" }, "readiness": { "enum": [ "ready", "provisioning", "unavailable" ] }, "total_rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "included_quotas": { "type": "object", "additionalProperties": false, "required": [ "included_disk_gib", "included_egress_gib" ], "properties": { "included_disk_gib": { "type": "integer", "minimum": 0 }, "included_egress_gib": { "type": "integer", "minimum": 0 } } }, "available_from": { "$ref": "#/components/schemas/Rfc3339Utc" }, "available_until": { "$ref": "#/components/schemas/Rfc3339Utc" }, "maintenance_windows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "starts_at", "ends_at", "reason" ], "properties": { "starts_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "ends_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "reason": { "type": "string" } } } }, "gpu_count": { "type": "integer", "minimum": 1 }, "model": { "type": "string" }, "vram_bytes": { "$ref": "#/components/schemas/DecimalString" }, "region": { "type": "string" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Additive. ISO 3166-1 alpha-2 country of the machine, read by the controller from the agent's request country as reported by the trusted proxy (never from host input). Absent when unknown." }, "continent": { "$ref": "#/components/schemas/Continent" }, "ram_bytes": { "$ref": "#/components/schemas/DecimalString" }, "disk_bytes": { "$ref": "#/components/schemas/DecimalString" }, "measured_bandwidth_mbps": { "type": "integer", "minimum": 0, "description": "netfacts lane. Measured DOWNLOAD rate in Mbps; additive. Absent = never measured (never 0)." }, "net_up_mbps": { "type": "integer", "minimum": 0, "description": "netfacts lane. Measured UPLOAD rate in Mbps; rides the same measurement as measured_bandwidth_mbps." }, "net_latency_ms": { "type": "integer", "minimum": 0, "description": "netfacts lane. Median HTTPS latency in ms from the same measurement." }, "speedtest_at": { "$ref": "#/components/schemas/Rfc3339Utc", "description": "netfacts lane. When the current net facts were measured; renders 'measured N ago' honestly." }, "tflops_bf16": { "type": "number", "exclusiveMinimum": 0, "description": "AI Speed. Measured dense BF16 matmul TFLOPS per GPU (the MIN across the machine's GPUs); additive. Absent = never measured (never 0)." }, "tflops_total": { "type": "number", "exclusiveMinimum": 0, "description": "AI Speed. tflops_bf16 x gpu_count, computed, one decimal. Absent with tflops_bf16 or gpu_count." }, "mem_bw_gbps": { "type": "number", "exclusiveMinimum": 0, "description": "AI Speed. Measured device memory bandwidth in GB/s per GPU (the MIN across the machine's GPUs). Absent = never measured (never 0)." }, "ai_speed": { "type": "integer", "minimum": 1, "description": "AI Speed. round(100*sqrt((tflops_bf16/165.2)*(mem_bw_gbps/1008))); RTX 4090 = 100. Absent unless both figures were measured." }, "bench_at": { "$ref": "#/components/schemas/Rfc3339Utc", "description": "AI Speed. When the current figures were measured." }, "bench_flag": { "type": "string", "enum": [ "unverified_spec" ], "description": "AI Speed. The GPU has no datasheet row to check the figures against." }, "disk_free_bytes": { "$ref": "#/components/schemas/DecimalString", "description": "Additive. Free disk space in bytes from the machine's latest telemetry sample. Absent when there is no sample, the sample is older than 60 seconds (2x the 30 s heartbeat, the host console STALE_AFTER_S rule) or the agent did not report it; never 0 as a stand-in." }, "uptime_s": { "$ref": "#/components/schemas/DecimalString", "description": "Additive. Seconds since the machine booted, from the latest telemetry sample. Absent under the same rules as disk_free_bytes." }, "gpu_utilization_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Additive. Live GPU load, the PEAK across the machine's devices, from the latest telemetry sample. Absent under the same rules as disk_free_bytes, and when no device reported utilisation. 0 means measured idle." }, "telemetry_at": { "$ref": "#/components/schemas/Rfc3339Utc", "description": "Additive. observed_at of the telemetry sample disk_free_bytes, uptime_s and gpu_utilization_pct came from. Present only with at least one of them; absent whenever they are." }, "template_compatibility": { "type": "array", "items": { "type": "string" } }, "manifest_hash": { "$ref": "#/components/schemas/Sha256Hash" }, "fit": { "$ref": "#/components/schemas/TemplateFit", "description": "D-19(c). Present only when the request carried template_id; computed server-side from the template vram_fit against measured device VRAM." }, "fits_template_ids": { "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "description": "Additive. Present only when the request carried fits_for=all; the ids of every published template that fits this offer (the same rule as fit)." }, "platform_fee_bps": { "type": "integer", "minimum": 0, "description": "Additive. Platform fee frozen into this offer version, in basis points (500 = 5%), taken out of each charge." }, "verification_level": { "enum": [ "unverified", "auto_verified", "manually_verified" ], "description": "Additive. How the machine's hardware claims were verified." }, "admitted": { "type": "boolean", "description": "Additive. Whether the machine has passed admission (a passed qualification for its current manifest). false is an unverified listing: shown in the catalog, never quoted or reserved (409 CONFLICT)." }, "tier": { "enum": [ "container", "inference" ], "description": "Additive (D-23). container: SSH containers under the launch profile. inference: managed models on a signed, hash-pinned runtime with no renter code, reached over the host's outbound session (community inference: don't send sensitive data)." }, "backends": { "description": "Additive. Backends the machine's devices serve, in preference order (cuda > rocm > sycl > vulkan > metal). A template runs here with the first one it has a runtime for.", "type": "array", "items": { "enum": [ "cuda", "rocm", "sycl", "vulkan", "metal" ] } }, "reliability": { "description": "Additive. Approximate reliability score from machine fields only (no per-job joins on the catalog path).", "type": "object", "additionalProperties": false, "required": [ "score", "stars", "band", "approximate" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "stars": { "type": "string" }, "band": { "type": "string" }, "approximate": { "type": "boolean" } } }, "availability_class": { "$ref": "#/components/schemas/AvailabilityClass" }, "preemption_notice_s": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 3600 }, { "type": "null" } ], "description": "D-22. Notice in seconds (SIGTERM plus /work/.amplerun-preempt) before the host stops an interruptible rental; null for dedicated." }, "interruption_estimate": { "description": "D-22. Present for interruptible offers (horizon 4 h in the catalog); null for dedicated.", "anyOf": [ { "$ref": "#/components/schemas/InterruptionEstimate" }, { "type": "null" } ] } }, "description": "No host management address is ever exposed. gpu_count, model and vram_bytes come from the machine manifest; vram_bytes is per GPU and is absent when the GPUs differ or memory was not measured. region, ram_bytes and disk_bytes are absent when the host did not measure them, never 0.", "example": { "offer_id": "8b0c2f4e-1d3a-4c5b-9e6f-7a8b9c0d1e2f", "machine_id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f", "observed_at": "2026-09-25T12:00:00Z", "offer_version": "3", "expected_version": "12", "readiness": "ready", "total_rate_micro_per_hour": "450000", "platform_fee_bps": 500, "included_quotas": { "included_disk_gib": 100, "included_egress_gib": 50 }, "available_from": "2026-09-25T00:00:00Z", "available_until": "2026-10-25T00:00:00Z", "maintenance_windows": [], "gpu_count": 1, "model": "NVIDIA GeForce RTX 4090", "vram_bytes": "25757220864", "region": "us-east-1", "manifest_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "verification_level": "auto_verified", "admitted": true, "fit": { "fits": true, "reason": "ok" } } } ``` ## Continent ```json { "description": "Additive. Continent derived from country: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. Absent when the country is unknown.", "enum": [ "AF", "AN", "AS", "EU", "NA", "OC", "SA" ] } ``` ## ContinentFilter ```json { "description": "A continent code, case-insensitive, or americas (North and South America).", "enum": [ "af", "an", "as", "eu", "na", "oc", "sa", "americas", "AF", "AN", "AS", "EU", "NA", "OC", "SA" ] } ``` ## Quote ```json { "type": "object", "additionalProperties": false, "required": [ "quote_id", "expires_at", "machine_id", "gpu_count", "machine_rate_micro_per_hour", "platform_fee_bps", "budget_micro", "duration_limit_s", "manifest_hash", "image_digest", "terms_version", "meter_start" ], "properties": { "quote_id": { "$ref": "#/components/schemas/UUID" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc", "description": "Quotes expire after 60 seconds." }, "machine_id": { "$ref": "#/components/schemas/UUID" }, "gpu_count": { "type": "integer", "minimum": 1 }, "machine_rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "platform_fee_bps": { "type": "integer", "minimum": 0 }, "budget_micro": { "$ref": "#/components/schemas/MicroAmount" }, "duration_limit_s": { "type": "integer", "minimum": 1 }, "included_disk_gib": { "type": "integer", "minimum": 0 }, "included_egress_gib": { "type": "integer", "minimum": 0 }, "manifest_hash": { "$ref": "#/components/schemas/Sha256Hash" }, "image_digest": { "$ref": "#/components/schemas/ImageDigest" }, "terms_version": { "type": "string" }, "meter_start": { "const": "verified_ready" }, "template_id": { "$ref": "#/components/schemas/UUID", "description": "D-19(c): echoed when the quote was created for a template." }, "image_ref": { "type": "string", "description": "Echoed when the request named a custom image by image_ref; image_digest is what it was pinned to." }, "estimated_total_micro": { "$ref": "#/components/schemas/MicroAmount", "description": "D-19(c): floor(total_rate_micro_per_hour * duration_limit_s / 3600), fee included; informational — the quote's budget_micro remains the only price authority." }, "asset": { "enum": [ "USDC", "USDT" ], "description": "Additive. Settlement asset whose balance the reservation holds; USDC unless the request chose USDT." }, "availability_class": { "$ref": "#/components/schemas/AvailabilityClass" }, "preemption_notice_s": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 3600 }, { "type": "null" } ], "description": "D-22. Notice in seconds before an interruptible rental is stopped; null for dedicated." }, "interruption_estimate": { "description": "D-22. For an interruptible quote, computed with horizon_h = the quoted duration rounded up to whole hours; null for dedicated.", "anyOf": [ { "$ref": "#/components/schemas/InterruptionEstimate" }, { "type": "null" } ] } }, "example": { "quote_id": "0c1d2e3f-4a5b-4c6d-8e7f-8091a2b3c4d5", "expires_at": "2026-09-25T12:01:00Z", "machine_id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f", "gpu_count": 1, "machine_rate_micro_per_hour": "450000", "platform_fee_bps": 500, "budget_micro": "1000000", "duration_limit_s": 7200, "included_disk_gib": 100, "included_egress_gib": 50, "manifest_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "image_digest": "registry.amplerun.com/templates/pytorch-cuda@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "terms_version": "rental-v1", "meter_start": "verified_ready", "template_id": "a35d15fe-ab57-4283-87f8-a00528d1d631", "estimated_total_micro": "900000", "asset": "USDC" } } ``` ## Job ```json { "type": "object", "additionalProperties": false, "required": [ "job_id", "state", "cumulative_charge_micro", "funded_through", "budget_version" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "state": { "enum": [ "RESERVED", "STARTING", "RUNNING", "STOPPING", "STOPPED", "CLEANING", "CLOSED", "FAILED", "RECONCILING" ] }, "cumulative_charge_micro": { "$ref": "#/components/schemas/MicroAmount" }, "funded_through": { "$ref": "#/components/schemas/Rfc3339Utc" }, "budget_version": { "$ref": "#/components/schemas/DecimalString" }, "machine_id": { "$ref": "#/components/schemas/UUID" }, "fence": { "$ref": "#/components/schemas/DecimalString" }, "rate_micro_per_hour": { "description": "Additive. The rate agreed at reservation, read from the job's quote snapshot (quotes.machine_rate_micro_per_hour). Evidence only: never recomputed from current offers, never an input to billing or state.", "allOf": [ { "$ref": "#/components/schemas/MicroAmount" } ] }, "accepted_runtime_ms": { "description": "Additive. Control-owned accepted-runtime accumulator; 0 before any accepted receipt.", "allOf": [ { "$ref": "#/components/schemas/DecimalString" } ] }, "meter_started_at": { "description": "Additive. When the meter actually started (verified READY), not when the job was reserved. null means \"not yet measured\" — distinct from zero.", "oneOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "last_meter_receipt_at": { "description": "Additive. Observation time (wall_time) of the most recent ACCEPTED meter receipt. null when no receipt has been accepted yet — a RUNNING job with meter_started_at set may still have this null.", "oneOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "stopped_at": { "description": "Additive. When the machine confirmed the stop (jobs.stopped_at). Set once the job reaches STOPPED; null before, and null when no stop was confirmed. Display only.", "oneOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "tier": { "description": "Additive (D-23). The machine's tier; inference is community inference (don't send sensitive data).", "enum": [ "container", "inference" ] }, "gpu_model": { "description": "Additive. The GPU model the machine's agent reported (its manifest), for naming the deployment (\"Qwen3 8B · RTX 4090\"). Absent when the agent reported none. Display only, never billing input.", "type": "string", "minLength": 1 }, "gpu_count": { "description": "Additive. How many of `gpu_model` the machine has, from the same manifest. Absent with gpu_model.", "type": "integer", "minimum": 1 }, "template": { "description": "Additive. Present only when the job's quote named a template (quotes.template_id); summary of templates.spec.", "type": "object", "additionalProperties": false, "required": [ "template_id", "name", "kind" ], "properties": { "template_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" }, "name": { "type": "string", "minLength": 1 }, "kind": { "enum": [ "model", "classical", "custom" ] } } } }, "example": { "job_id": "7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b", "state": "RUNNING", "cumulative_charge_micro": "112500", "funded_through": "2026-09-25T14:00:00Z", "budget_version": "1", "machine_id": "5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f", "fence": "4", "rate_micro_per_hour": "450000", "accepted_runtime_ms": "900000", "meter_started_at": "2026-09-25T12:02:10Z", "last_meter_receipt_at": "2026-09-25T12:17:10Z", "template": { "template_id": "pytorch-cuda", "name": "PyTorch (CUDA)", "kind": "classical" } } } ``` ## JobEvent ```json { "type": "object", "additionalProperties": false, "required": [ "seq", "type", "at" ], "properties": { "seq": { "$ref": "#/components/schemas/DecimalString" }, "type": { "type": "string" }, "at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "detail": { "type": "object" } } } ``` ## DepositAddress ```json { "type": "object", "additionalProperties": false, "required": [ "chain_id", "network", "address", "assets", "min_deposit_micro", "max_deposit_micro", "finalized_block_number", "networks", "deposits" ], "properties": { "chain_id": { "type": "integer", "enum": [ 8453 ] }, "network": { "type": "string", "enum": [ "base" ] }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "networks": { "description": "Every network this address is watched on right now (Base first). The address is the same on each. Stablecoins credit 1:1; the native coin credits in USD at the Chainlink price at finality minus spread_bps.", "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "chain_id", "caip2", "name", "native_symbol", "explorer_url", "assets", "native", "status", "finalized_block_number" ], "properties": { "key": { "type": "string", "enum": [ "base", "arbitrum", "ethereum", "optimism", "polygon", "bnb", "avalanche", "sei", "xlayer", "robinhood", "arc" ] }, "chain_id": { "type": "integer" }, "caip2": { "type": "string", "pattern": "^eip155:[0-9]+$" }, "name": { "type": "string" }, "native_symbol": { "type": "string" }, "explorer_url": { "type": "string", "format": "uri" }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asset", "contract" ], "properties": { "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "contract": { "$ref": "#/components/schemas/EvmAddress" } } } }, "native": { "description": "null when the native coin is not credited on this network.", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "symbol", "spread_bps", "quote_micro_per_coin", "price_updated_at" ], "properties": { "symbol": { "type": "string" }, "spread_bps": { "type": "integer", "minimum": 0, "maximum": 1000 }, "quote_micro_per_coin": { "description": "Live quote for one whole coin after the spread (display only; the credit uses the price at finality).", "anyOf": [ { "$ref": "#/components/schemas/MicroAmount" }, { "type": "null" } ] }, "price_updated_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "OK", "UNAVAILABLE" ] }, "finalized_block_number": { "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "wallet_add_chain": { "description": "EIP-3085 wallet_addEthereumChain parameters (public RPC and explorer), for a wallet that doesn't know this network yet. Read-only; null when no public RPC is known. Absent from older servers.", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "chainId", "chainName", "nativeCurrency", "rpcUrls", "blockExplorerUrls" ], "properties": { "chainId": { "type": "string", "pattern": "^0x[0-9a-f]+$" }, "chainName": { "type": "string" }, "nativeCurrency": { "type": "object", "additionalProperties": false, "required": [ "name", "symbol", "decimals" ], "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0 } } }, "rpcUrls": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } }, "blockExplorerUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, { "type": "null" } ] } } } }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asset", "contract" ], "properties": { "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "contract": { "$ref": "#/components/schemas/EvmAddress" } } } }, "min_deposit_micro": { "$ref": "#/components/schemas/MicroAmount" }, "max_deposit_micro": { "description": "Room left under the account balance cap; null = no limit.", "anyOf": [ { "$ref": "#/components/schemas/MicroAmount" }, { "type": "null" } ] }, "finalized_block_number": { "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "deposits": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "chain_id", "network", "tx_hash", "log_index", "asset", "amount_micro", "amount_wei", "block_number", "state", "blocks_to_finality", "reason", "created_at" ], "properties": { "chain_id": { "type": "integer" }, "network": { "type": "string" }, "tx_hash": { "description": "null for a native-coin credit (credited from the address balance at finality, not per transaction).", "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, { "type": "null" } ] }, "log_index": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "asset": { "type": "string", "enum": [ "USDC", "USDT", "ETH", "POL", "BNB", "AVAX" ] }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "amount_wei": { "description": "Native coins only, in the coin's base unit.", "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "block_number": { "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "SEEN", "CREDITED", "HELD" ] }, "blocks_to_finality": { "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } } } } } } ``` ## BalanceSet ```json { "type": "object", "additionalProperties": false, "required": [ "spendable_micro", "held_micro", "pending_micro", "disputed_micro", "withdrawable_micro", "spend_30d_micro", "spend_window_from", "spend_window_to", "active_hold_micro" ], "properties": { "spendable_micro": { "$ref": "#/components/schemas/MicroAmount" }, "held_micro": { "$ref": "#/components/schemas/MicroAmount" }, "pending_micro": { "$ref": "#/components/schemas/MicroAmount" }, "disputed_micro": { "$ref": "#/components/schemas/MicroAmount" }, "withdrawable_micro": { "$ref": "#/components/schemas/MicroAmount" }, "spend_30d_micro": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "spend_window_from": { "$ref": "#/components/schemas/Rfc3339Utc" }, "spend_window_to": { "$ref": "#/components/schemas/Rfc3339Utc" }, "active_hold_micro": { "$ref": "#/components/schemas/MicroAmount" }, "confirming_micro": { "description": "Stablecoin deposits credited before chain finality. Already in spendable_micro (usable for rentals), not yet in withdrawable_micro; they become withdrawable once final, or are reversed if the chain drops them.", "$ref": "#/components/schemas/MicroAmount" }, "confirming_ready_at": { "description": "When the last confirming deposit should be final (the chain's typical finality lag); null when none is confirming. An estimate, not a promise.", "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } }, "example": { "spendable_micro": "4000000", "held_micro": "1000000", "pending_micro": "0", "disputed_micro": "0", "withdrawable_micro": "4000000", "spend_30d_micro": "2500000", "spend_window_from": "2026-08-26T00:00:00Z", "spend_window_to": "2026-09-25T00:00:00Z", "active_hold_micro": "1000000" } } ``` ## WalletBinding ```json { "type": "object", "additionalProperties": false, "required": [ "binding_id", "chain_id", "address", "version", "linked_at", "unlinked_at" ], "properties": { "binding_id": { "$ref": "#/components/schemas/UUID" }, "chain_id": { "const": 8453 }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "version": { "$ref": "#/components/schemas/DecimalString" }, "linked_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "unlinked_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } } } ``` ## WithdrawalAddress ```json { "description": "A saved withdrawal / payout address (034). CONFIRMED by its email link (or the account's sign-in wallet); PENDING until then.", "type": "object", "additionalProperties": false, "required": [ "id", "network", "chain_id", "address", "label", "state", "version", "created_at", "confirmed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "network": { "type": "string", "enum": [ "base" ] }, "chain_id": { "type": "integer" }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "label": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "PENDING", "CONFIRMED" ] }, "version": { "$ref": "#/components/schemas/DecimalString" }, "created_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "confirmed_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } } } ``` ## TransferRequest ```json { "description": "A withdrawal or host payout to a typed address. Sessions confirm with `code`: the authenticator code when the account has 2FA, else the 6-digit code from POST /api/v1/withdrawals/code. A wallet-only account (no email) sends `siwe_message` + `signature` (a step-up challenge from its sign-in wallet) instead. API keys send no code and reach saved (CONFIRMED) addresses only.", "type": "object", "additionalProperties": false, "required": [ "address", "amount_micro" ], "properties": { "network": { "type": "string", "enum": [ "base" ], "description": "Defaults to base." }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ], "description": "Defaults to USDC." }, "label": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Saved with a new address." }, "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "siwe_message": { "type": "string", "minLength": 1 }, "signature": { "type": "string", "minLength": 1 } } } ``` ## TransferAccepted ```json { "description": "INTENT: queued to a saved address (withdrawal_id or payout_id set). AWAITING_EMAIL_CONFIRMATION: a new address; nothing is locked until the emailed link (30 min) is opened, which queues exactly this request.", "type": "object", "additionalProperties": false, "required": [ "state", "address_id", "asset" ], "properties": { "state": { "type": "string", "enum": [ "INTENT", "AWAITING_EMAIL_CONFIRMATION" ] }, "withdrawal_id": { "$ref": "#/components/schemas/UUID" }, "payout_id": { "$ref": "#/components/schemas/UUID" }, "confirmation_id": { "$ref": "#/components/schemas/UUID" }, "address_id": { "$ref": "#/components/schemas/UUID" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] } } } ``` ## ApiKeyView ```json { "description": "API key metadata. The secret itself appears only in the creation response.", "type": "object", "required": [ "key_id", "label", "prefix", "scopes", "expires_at", "revoked_at", "created_at" ], "properties": { "key_id": { "$ref": "#/components/schemas/UUID" }, "label": { "type": "string" }, "prefix": { "type": "string", "description": "First 12 characters of the key, for recognising it." }, "scopes": { "type": "array", "items": { "enum": [ "renter", "host" ] } }, "expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } ``` ## Template ```json { "description": "Public template (D-19(b)); mirrors packages/contracts/schemas/template.schema.json, which remains the authority for templates.spec. kind=model requires model_ref and readiness.", "type": "object", "additionalProperties": false, "required": [ "id", "published", "template_id", "name", "template_version", "image_digest", "launch_profile_version", "kind", "engine", "vram_fit", "exposes", "env", "min_gpu_count", "required_runtime", "setup_notes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "published": { "type": "boolean" }, "template_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" }, "name": { "type": "string", "minLength": 1 }, "template_version": { "type": "string", "minLength": 1 }, "image_digest": { "$ref": "#/components/schemas/ImageDigest", "description": "Pinned OCI reference (name@sha256:<64 hex>) — the same form quotes, START commands and qualification records carry." }, "launch_profile_version": { "type": "string", "minLength": 1 }, "kind": { "enum": [ "model", "classical", "custom" ] }, "engine": { "enum": [ "vllm", "llamacpp", "comfyui", "faster-whisper", "pytorch", "jupyter", "ollama", "oci" ] }, "model_ref": { "type": "object", "additionalProperties": false, "required": [ "hf_repo", "revision", "files" ], "properties": { "hf_repo": { "type": "string", "minLength": 1 }, "revision": { "type": "string", "minLength": 1 }, "files": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "sha256", "size_bytes" ], "properties": { "name": { "type": "string", "pattern": "^(?!\\.\\.?$)[A-Za-z0-9._-]+$" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "size_bytes": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "quantization": { "type": "string", "minLength": 1 }, "vram_fit": { "type": "object", "additionalProperties": false, "required": [ "min_vram_bytes", "est_weights_bytes", "est_kv_bytes_per_1k_tokens" ], "properties": { "min_vram_bytes": { "$ref": "#/components/schemas/DecimalString" }, "est_weights_bytes": { "$ref": "#/components/schemas/DecimalString" }, "est_kv_bytes_per_1k_tokens": { "$ref": "#/components/schemas/DecimalString" } } }, "readiness": { "type": "object", "additionalProperties": false, "required": [ "http_path", "expect_status" ], "properties": { "http_path": { "type": "string", "pattern": "^/" }, "expect_status": { "type": "integer", "minimum": 100, "maximum": 599 } } }, "exposes": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "port", "protocol" ], "properties": { "name": { "type": "string", "minLength": 1 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "protocol": { "enum": [ "http", "ssh", "tcp" ] } } } }, "env": { "type": "object", "propertyNames": { "pattern": "^[A-Z][A-Z0-9_]{1,63}$" }, "additionalProperties": { "type": "string" } }, "min_gpu_count": { "type": "integer", "minimum": 1 }, "required_runtime": { "enum": [ "cuda", "rocm-hip", "level-zero", "opencl", "xpu" ] }, "setup_notes": { "type": "string" }, "runtimes": { "description": "Additive. One template, many backends: the same weights and API contract per backend. tier container is an OCI image; tier inference is the signed Tier B runtime artifact (@sha256:). The control plane picks the machine's runtime by preference (cuda > rocm > sycl > vulkan > metal) and pins its digest in the quote and lease.", "type": "object", "additionalProperties": false, "properties": { "cuda": { "$ref": "#/components/schemas/TemplateRuntime" }, "rocm": { "$ref": "#/components/schemas/TemplateRuntime" }, "sycl": { "$ref": "#/components/schemas/TemplateRuntime" }, "vulkan": { "$ref": "#/components/schemas/TemplateRuntime" }, "metal": { "$ref": "#/components/schemas/TemplateRuntime" } } }, "backends": { "description": "Additive. Backends with a built runtime, in preference order (\"Works on\" filter). Spec compatibility, not a hardware test.", "type": "array", "items": { "enum": [ "cuda", "rocm", "sycl", "vulkan", "metal" ] } }, "works_on": { "description": "Additive. Hardware vendors those backends cover. Spec compatibility only; a hardware report is what says \"tested on\".", "type": "array", "items": { "enum": [ "nvidia", "amd", "intel", "apple" ] } } } } ``` ## TemplateRuntime ```json { "type": "object", "additionalProperties": false, "required": [ "tier", "image_digest" ], "properties": { "tier": { "enum": [ "container", "inference" ] }, "image_digest": { "$ref": "#/components/schemas/ImageDigest" } } } ``` ## TemplateFit ```json { "description": "D-19(c) per-offer fit verdict for a template, computed server-side from vram_fit against measured device VRAM. reason is human-readable and non-empty when fits is false.", "type": "object", "additionalProperties": false, "required": [ "fits", "reason" ], "properties": { "fits": { "type": "boolean" }, "reason": { "type": "string" } } } ``` ## TelemetrySample ```json { "description": "Task A machine telemetry sample, mirroring telemetry.schema.json (the cross-language authority). EVERY measurement is optional: a probe that failed or was absent omits its field entirely. An absent field means \"not measured\", never 0 and never the previous reading. Byte/second counters are decimal strings; percentages and temperatures are bounded numbers.", "type": "object", "required": [ "devices" ], "properties": { "devices": { "type": "array", "items": { "type": "object", "required": [ "pci_address" ], "properties": { "pci_address": { "type": "string" }, "temperature_c": { "type": "number" }, "utilization_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "memory_used_bytes": { "$ref": "#/components/schemas/DecimalString" }, "power_watts": { "type": "number", "minimum": 0 }, "fan_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "vendor": { "type": "string", "enum": [ "nvidia", "amd", "intel", "apple" ] }, "uuid": { "type": "string", "description": "Normalised device UUID (GPU-/MIG- prefix stripped, lowercase)." }, "memory_total_bytes": { "$ref": "#/components/schemas/DecimalString" }, "unified_memory_used_bytes": { "$ref": "#/components/schemas/DecimalString" }, "health": { "type": "object", "description": "Absent = this vendor gives no health signal. ok=false carries the reason.", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string" } } }, "source": { "type": "string", "enum": [ "lib", "cli", "sysfs" ] } } } }, "host": { "type": "object", "properties": { "cpu_utilization_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "memory_used_bytes": { "$ref": "#/components/schemas/DecimalString" }, "disk_free_bytes": { "$ref": "#/components/schemas/DecimalString" }, "uptime_s": { "$ref": "#/components/schemas/DecimalString" }, "load1": { "type": "number", "minimum": 0 } } } } } ``` ## TelemetryNumberSummary ```json { "description": "Min/avg/max of one measured numeric field within a 5-minute bucket. Present only when the field was measured at least once in that bucket.", "type": "object", "additionalProperties": false, "required": [ "min", "avg", "max" ], "properties": { "min": { "type": "number" }, "avg": { "type": "number" }, "max": { "type": "number" } } } ``` ## TelemetryAmountSummary ```json { "description": "Min/avg/max of one measured byte/second counter within a 5-minute bucket, as exact decimal strings (avg is floored; a byte count is never a float).", "type": "object", "additionalProperties": false, "required": [ "min", "avg", "max" ], "properties": { "min": { "$ref": "#/components/schemas/DecimalString" }, "avg": { "$ref": "#/components/schemas/DecimalString" }, "max": { "$ref": "#/components/schemas/DecimalString" } } } ``` ## X402PaymentRequired ```json { "description": "x402 v2 PaymentRequired. accepts has one entry, the exact EIP-3009 USDC payment to the treasury.", "type": "object", "required": [ "x402Version", "error", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "error": { "type": "string" }, "resource": { "type": "object", "required": [ "url", "description", "mimeType" ], "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string", "description": "CAIP-2, \"eip155:8453\" (Base)." }, "amount": { "$ref": "#/components/schemas/DecimalString" }, "asset": { "type": "string", "description": "Pinned native USDC contract (EIP-712 verifying contract)." }, "payTo": { "type": "string", "description": "The treasury." }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "required": [ "assetTransferMethod", "name", "version" ], "properties": { "assetTransferMethod": { "type": "string", "enum": [ "eip3009" ] }, "name": { "type": "string", "description": "EIP-712 domain name." }, "version": { "type": "string", "description": "EIP-712 domain version." } } } } } } } } ``` ## X402TopUp ```json { "type": "object", "required": [ "intent_id", "state", "amount_micro", "payer", "tx_hash", "log_index", "network" ], "properties": { "intent_id": { "$ref": "#/components/schemas/UUID" }, "state": { "type": "string", "enum": [ "PENDING_FINALITY", "CONFIRMED", "EXCEPTION" ] }, "amount_micro": { "$ref": "#/components/schemas/DecimalString" }, "credited_micro": { "$ref": "#/components/schemas/DecimalString" }, "reason": { "type": "string" }, "payer": { "type": "string", "description": "The wallet that signed the authorization. It need not be linked to the account." }, "tx_hash": { "type": "string" }, "log_index": { "type": "integer" }, "network": { "type": "string" } } } ``` --- Generated from the AmpleRun API contract. Canonical: https://docs.amplerun.com/reference/schemas/