{ "openapi": "3.1.0", "info": { "title": "AmpleRun Business API", "version": "3.0.0", "description": "AmpleRun business HTTP surface, contract version 3 (supersedes contract 2; see docs/DECISIONS.md D-16/D-17).\n\nShared wire rules: JSON over HTTPS; UUID identifiers; RFC3339 UTC timestamps; monetary and\nmillisecond quantities are base-10 integer STRINGS; basis points are integers. Errors use\n`{error:{code,message,retryable,request_id}}` and never include stack traces or secrets.\nEvery mutating financial/job request carries an `Idempotency-Key` UUID scoped to authenticated\nprincipal, route and canonical request hash; same key/body returns the original result, same\nkey/different body returns 409 IDEMPOTENCY_CONFLICT. Auth failures 401; authenticated forbidden\n403 (or 404 to avoid leaking existence); invalid input 422; unavailable money/provider state 503\nwith retryable:true; resource/budget conflicts 409. Async work returns 202 with a persisted\njob/operation ID. Lists use opaque cursor pagination (default 20, max 100). No cached public\naccount/financial responses (private/no-store). USD reference prices settle 1:1 in USDC units\nunder disclosed pricing terms with USDC depeg risk disclosed.\n\nMoney is in micro-units of the settlement asset: \"5000000\" is 5 USDC. The platform fee is taken\nout of each charge, never added on top: fee = floor(charge * platform_fee_bps / 10000) and the\nhost receives charge - fee. Programs authenticate with an API key sent as\n`Authorization: Bearer ark_...` (see the sessionAuth scheme). Rate-limited routes answer 429\nwith code UNAVAILABLE and retryable:true; no Retry-After header is sent, so back off\nexponentially. AI agents can use the MCP server @amplerun/mcp, which wraps this API.\n" }, "servers": [ { "url": "https://amplerun-api.spiry.org", "description": "Production machine API (direct origin)" }, { "url": "https://amplerun.com", "description": "Production frontend-compatible API origin" } ], "externalDocs": { "description": "Guides, SDKs, CLI and the MCP server for AI agents", "url": "https://amplerun.com/docs/api" }, "tags": [ { "name": "catalog", "description": "Public templates and GPU offers. No credential needed." }, { "name": "jobs", "description": "Quote, reserve, inspect and stop rentals (a job is one rental). Renter scope." }, { "name": "account", "description": "Profile, sessions, API keys and third-party tokens for the caller." }, { "name": "agents", "description": "An AI agent registers its own account with a wallet signature (EIP-4361). No email, no person in the loop." }, { "name": "wallets", "description": "SIWE wallet bindings on Base and the payout destination." }, { "name": "billing", "description": "Balances, ledger entries, receipts, funding intents and withdrawals." }, { "name": "hosts", "description": "Machines, offers, telemetry, earnings and payouts for hosts. Host scope." }, { "name": "support", "description": "Support tickets." }, { "name": "admin", "description": "Operator console. Admin session with TOTP only; API keys are rejected." }, { "name": "health", "description": "Liveness, readiness and public status. No credential needed." } ], "components": { "securitySchemes": { "sessionAuth": { "type": "http", "scheme": "bearer", "description": "Bearer credential. Programs and agents send a scoped API key as `Authorization: Bearer ark_...` (renter and/or host scope; created once at https://amplerun.com/account#api-keys or POST /api/v1/account/api-keys; the secret is shown only at creation). The web app uses a pinned Better Auth session. API keys never reach /api/v1/admin/*. Step-up (recent re-auth) is required where noted." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/UUID" }, "description": "UUID scoped to authenticated principal, route and canonical request hash." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor from a previous response." }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } }, "schemas": { "UUID": { "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": { "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": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Unsigned base-10 integer as string; never a float.", "example": "1" }, "MicroAmount": { "$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": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x1111111111111111111111111111111111111111" }, "Sha256Hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "example": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "ImageDigest": { "type": "string", "pattern": "^[^@\\s]+@sha256:[0-9a-f]{64}$", "example": "registry.amplerun.com/templates/pytorch-cuda@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "ErrorEnvelope": { "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": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "SettingView": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "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": { "type": "object", "additionalProperties": false, "required": [ "tier", "image_digest" ], "properties": { "tier": { "enum": [ "container", "inference" ] }, "image_digest": { "$ref": "#/components/schemas/ImageDigest" } } }, "TemplateFit": { "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": { "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": { "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": { "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": { "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": { "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" } } } }, "responses": { "AgentAccountRegistered": { "description": "The agent's account (201 new, 200 existing) and a new API key. The secret is shown only here.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "account_id", "account_kind", "created", "address", "terms_version", "api_key", "next_steps" ], "properties": { "account_id": { "type": "string" }, "account_kind": { "type": "string", "enum": [ "agent", "human" ] }, "created": { "type": "boolean" }, "address": { "type": "string", "description": "Lowercase wallet address." }, "terms_version": { "type": "string" }, "api_key": { "type": "object", "additionalProperties": false, "required": [ "key_id", "secret", "prefix", "scopes" ], "properties": { "key_id": { "$ref": "#/components/schemas/UUID" }, "secret": { "type": "string", "description": "ark_... Send as Authorization: Bearer ." }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "renter", "host" ] } } } }, "next_steps": { "type": "object", "additionalProperties": false, "required": [ "fund", "rent", "mcp" ], "properties": { "fund": { "type": "string" }, "rent": { "type": "string" }, "mcp": { "type": "string" } } } } } } } }, "Error": { "description": "Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "paths": { "/api/v1/auth/providers": { "get": { "operationId": "getSignInProviders", "tags": [ "account" ], "summary": "Configured social sign-in providers (public names only)", "security": [], "responses": { "200": { "description": "Currently composed providers; credentials are never returned.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "providers" ], "additionalProperties": false, "properties": { "providers": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "github", "google", "huggingface" ] } } } } } } } } } }, "/api/v1/offers": { "get": { "operationId": "listOffers", "tags": [ "catalog" ], "summary": "List admitted offers (public)", "description": "Listed offers on available, admitted machines with a heartbeat in the last 90 seconds; only these can be reserved. Server-side filters are model, gpu_count, max_rate_micro_per_hour, verification_level, continent and template_id; sort defaults to price_asc, and near puts one continent's machines first. There is no VRAM, region, RAM, disk or bandwidth filter: each item carries vram_bytes, region, ram_bytes and disk_bytes when measured, for client-side filtering. With template_id (D-19(c)) every item carries a server-computed fit object. No cached public responses.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "template_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UUID" }, "description": "Compute per-offer fit against this template's vram_fit (D-19(c)). The template's `id` (UUID), not its slug; resolve a slug with GET /api/v1/templates/{templateId}. Unknown or unpublished template -> 404, a slug -> 422." }, { "name": "fits_for", "in": "query", "required": false, "schema": { "enum": [ "all" ] }, "description": "Additive. `all` adds fits_template_ids to every item, the ids of every published template that fits that offer under the same rule as template_id, in one read. Any other value -> 422." }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "price_asc", "price_desc", "vram_desc", "reliability_desc", "uptime_desc", "newest", "verification", "net_desc", "tflops_desc", "ai_speed_desc" ], "default": "price_asc" }, "description": "Keyset sort order; an unknown value falls back to price_asc." }, { "name": "verification_level", "in": "query", "required": false, "schema": { "enum": [ "unverified", "auto_verified", "manually_verified" ] }, "description": "Only machines at exactly this verification level." }, { "name": "include_unverified", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Also list machines that have not passed admission yet." }, { "name": "min_bandwidth_mbps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "netfacts lane. Only machines whose MEASURED download rate is at least this; machines that never measured are excluded (they cannot claim a rate)." }, { "name": "max_rate_micro_per_hour", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MicroAmount" }, "description": "Only offers whose total machine rate is at or below this amount." }, { "name": "gpu_count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Only offers whose machine manifest lists at least this many devices." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Case-insensitive substring match on the first device model in the manifest." }, { "name": "tier", "in": "query", "required": false, "schema": { "enum": [ "container", "inference" ] }, "description": "Only machines of this tier (D-23)." }, { "name": "backend", "in": "query", "required": false, "schema": { "enum": [ "cuda", "rocm", "sycl", "vulkan", "metal" ] }, "description": "Only machines with a device serving this backend." }, { "name": "continent", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ContinentFilter" }, "description": "Only machines on this continent (americas = NA + SA). Machines with an unknown location are excluded. Any other value -> 422." }, { "name": "near", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ContinentFilter" }, "description": "Order this continent's machines first (lower latency), then by sort. Keeps every other machine. Any other value -> 422." } ], "responses": { "200": { "description": "Page of offer summaries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OfferSummary" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/offers/{id}": { "get": { "operationId": "getOffer", "tags": [ "catalog" ], "summary": "Get one offer (public)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Offer summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferSummary" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "tags": [ "catalog" ], "summary": "List published templates (public)", "description": "D-19(c). Cursor paged; filters kind and min_vram_bytes (templates whose vram_fit.min_vram_bytes <= the given value). Only published templates (bound to at least one admitted machine by a qualification record) are listed. No cached public responses.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "kind", "in": "query", "required": false, "schema": { "enum": [ "model", "classical", "custom" ] } }, { "name": "min_vram_bytes", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DecimalString" }, "description": "Return templates that fit a device with this much VRAM." }, { "name": "backend", "in": "query", "required": false, "schema": { "enum": [ "cuda", "rocm", "sycl", "vulkan", "metal" ] }, "description": "Only templates with a built runtime for this backend (\"Works on\")." } ], "responses": { "200": { "description": "Page of templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/templates/{templateId}": { "get": { "operationId": "getTemplate", "tags": [ "catalog" ], "summary": "Get one published template (public)", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Template UUID or its slug (spec.template_id, e.g. qwen3-8b-awq); unpublished -> 404." } ], "responses": { "200": { "description": "Template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/quotes": { "post": { "operationId": "createQuote", "tags": [ "jobs" ], "summary": "Create immutable quote (verified renter)", "description": "Returns an immutable quote with 60s expiry, terms version, machine manifest hash and total rate. Refresh stale catalog quotes before charging. Quoting is free and holds nothing; POST /api/v1/jobs reserves. The Idempotency-Key is not deduplicated on this route, so a retry returns a fresh quote. 409 CONFLICT when the offer's machine is not admitted: an unverified listing (OfferSummary admitted false) is shown but cannot be quoted or reserved until it passes qualification.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "offer_id", "duration_limit_s", "budget_micro" ], "description": "Exactly one of template_id, image_digest or image_ref (422 otherwise). With template_id the server resolves the published template's pinned image_digest and requires the offer to fit (422). An image_ref, or an image_digest no published template pins, is a custom image: it is accepted only while the marketplace enables custom images (422 otherwise), is resolved anonymously against an allowed public registry (docker.io, ghcr.io, quay.io, nvcr.io, public.ecr.aws) and quoted by its digest (422 when private, missing, not linux/amd64 or over the size cap), and only on a machine whose host opted in (422).", "properties": { "offer_id": { "$ref": "#/components/schemas/UUID" }, "image_digest": { "$ref": "#/components/schemas/ImageDigest", "description": "A published template's image, or a custom public image pinned by digest." }, "image_ref": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom public image by tag or digest ([registry/]repository[:tag][@sha256:...]); the server pins it to a digest at quote time." }, "duration_limit_s": { "type": "integer", "minimum": 1, "description": "Maximum runtime in seconds, metered from verified readiness." }, "budget_micro": { "$ref": "#/components/schemas/MicroAmount", "description": "Spending cap: the job is never charged more than this." }, "template_id": { "$ref": "#/components/schemas/UUID", "description": "D-19(c): published template; the server sets image_digest from it and the offer must fit, else 422. Mutually exclusive with image_digest. The template's `id` (UUID), not its slug." }, "asset": { "enum": [ "USDC", "USDT" ], "default": "USDC", "description": "Additive. Settlement asset whose balance the reservation holds; unknown values are 422." } } }, "example": { "offer_id": "8b0c2f4e-1d3a-4c5b-9e6f-7a8b9c0d1e2f", "template_id": "a35d15fe-ab57-4283-87f8-a00528d1d631", "duration_limit_s": 7200, "budget_micro": "1000000" } } } }, "responses": { "201": { "description": "Immutable quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs": { "post": { "operationId": "createJob", "tags": [ "jobs" ], "summary": "Reserve job from quote (quote owner)", "description": "Atomically holds budget, reserves machine, increments fence and queues start. Rejects expired quote (409 QUOTE_EXPIRED), changed manifest, unavailable or not admitted machine, or insufficient spendable funds (409 INSUFFICIENT_FUNDS) without partial holds. Replaying the same Idempotency-Key with the same body returns the original job, so a timed-out request is safe to retry; the same key with another body is 409 IDEMPOTENCY_CONFLICT and reserves nothing.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quote_id" ], "properties": { "quote_id": { "$ref": "#/components/schemas/UUID" }, "ssh_public_key": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "One-line OpenSSH public key installed for the tenant user. Optional: without it the server installs a generated key whose private half it discards, so SSH is off for that rental (model rentals chat through /jobs/{id}/openai/v1)." } } }, "example": { "quote_id": "0c1d2e3f-4a5b-4c6d-8e7f-8091a2b3c4d5", "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGVxYW1wbGVrZXlfbm90X3JlYWw you@laptop" } } } }, "responses": { "202": { "description": "Job reserved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "state" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "state": { "const": "RESERVED" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "listJobs", "tags": [ "jobs" ], "summary": "List own jobs (renter owner/admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of jobs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "jobs" ], "summary": "Job status, cumulative charge, funded-through (owner/admin)", "description": "Poll this after POST /api/v1/jobs. States run RESERVED -> STARTING -> RUNNING (verified ready; the meter starts here) -> STOPPING -> STOPPED -> CLEANING -> CLOSED, or FAILED / RECONCILING. GET /api/v1/jobs/{id}/access answers only while RUNNING (execution) or, for a limited window, after STOPPED (read-only retrieval); other states are 403.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Job detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/events": { "get": { "operationId": "listJobEvents", "tags": [ "jobs" ], "summary": "Sequenced job events (owner/admin); logs sanitized and bounded", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of sequenced events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/JobEvent" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/access": { "get": { "operationId": "getJobAccess", "tags": [ "jobs" ], "summary": "Current endpoint, SSH host-key fingerprint and command (renter owner)", "description": "Execution access only while ready/running; STOPPED retrieval access is read-only, time-limited and explicitly labeled. No execution endpoint before verified readiness.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Access material.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "mode", "endpoints", "ssh_host_key_fingerprint", "ssh_command", "expires_at" ], "properties": { "mode": { "enum": [ "execution", "retrieval-read-only" ] }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "endpoint_id", "kind", "external_host", "external_port" ], "properties": { "endpoint_id": { "type": "string" }, "kind": { "enum": [ "ssh", "https", "http", "sftp-retrieval" ] }, "external_host": { "type": "string" }, "external_port": { "type": "integer", "minimum": 1, "maximum": 65535 } } } }, "ssh_host_key_fingerprint": { "type": "string" }, "ssh_command": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "api_key": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Additive. Per-job bearer token for kind=model templates (mode=execution only); the same value the engine was launched with (AMPLERUN_API_KEY / VLLM_API_KEY / LLAMA_API_KEY). Never present for classical/custom jobs." } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/openai/v1/models": { "get": { "operationId": "relayListModels", "tags": [ "jobs" ], "summary": "OpenAI-compatible relay to a running model rental, list models (renter owner/admin)", "description": "One of four relay paths (models, chat/completions, completions, embeddings); any other path under /openai/v1 is 404. The server forwards to the rental's own leased http endpoint and adds the per-job key; client cookies and Authorization never reach the host. 409 unless the job is RUNNING with a model endpoint. Bodies over 1 MiB are 413. Rate-limited per account. Point any OpenAI client here as its base URL with an AmpleRun API key (renter scope).", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "The engine's model list, passed through.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/openai/v1/chat/completions": { "post": { "operationId": "relayChatCompletions", "tags": [ "jobs" ], "summary": "OpenAI-compatible relay, chat completions (renter owner/admin)", "description": "Same rules as the models path. With stream:true the response is text/event-stream, streamed unbuffered.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "model": "Qwen/Qwen3-32B-AWQ", "stream": true, "messages": [ { "role": "user", "content": "hello" } ] } } } }, "responses": { "200": { "description": "The engine's response, passed through (JSON, or SSE when stream:true).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/openai/v1/completions": { "post": { "operationId": "relayCompletions", "tags": [ "jobs" ], "summary": "OpenAI-compatible relay, text completions (renter owner/admin)", "description": "Same rules as the models path; stream:true streams text/event-stream.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The engine's response, passed through.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/openai/v1/embeddings": { "post": { "operationId": "relayEmbeddings", "tags": [ "jobs" ], "summary": "OpenAI-compatible relay, embeddings (renter owner/admin)", "description": "Same rules as the models path.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The engine's response, passed through.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/stop": { "post": { "operationId": "stopJob", "tags": [ "jobs" ], "summary": "Stop job (renter owner/admin); repeat is idempotent", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1 } } }, "example": { "reason": "training finished" } } } }, "responses": { "202": { "description": "STOPPING or original terminal result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "state" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "state": { "enum": [ "STOPPING", "STOPPED", "CLEANING", "CLOSED" ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/budget-extension": { "post": { "operationId": "extendJobBudget", "tags": [ "jobs" ], "summary": "Append funded budget amendment (renter owner)", "description": "Idempotent. Appends one immutable amendment plus hold atomically; keeps original rate and snapshotted host-availability ceiling; bumps budget_version. Rejects once STOPPING begins. D-16 — budget_version changes only with a committed funding amendment.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "additional_budget_micro", "new_duration_limit_s", "expected_job_version", "expected_budget_version" ], "properties": { "additional_budget_micro": { "$ref": "#/components/schemas/MicroAmount" }, "new_duration_limit_s": { "type": "integer", "minimum": 1 }, "expected_job_version": { "$ref": "#/components/schemas/DecimalString" }, "expected_budget_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Amendment committed; returns new budget_version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "budget_version", "funded_budget_micro" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "budget_version": { "$ref": "#/components/schemas/DecimalString" }, "funded_budget_micro": { "$ref": "#/components/schemas/MicroAmount" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/rerun": { "post": { "operationId": "rerunJob", "tags": [ "jobs" ], "summary": "Fresh quote parameters (renter owner); never launches/spends automatically", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Fresh quote parameters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "offer_id", "image_digest", "duration_limit_s", "budget_micro" ], "properties": { "offer_id": { "$ref": "#/components/schemas/UUID" }, "image_digest": { "$ref": "#/components/schemas/ImageDigest" }, "duration_limit_s": { "type": "integer", "minimum": 1 }, "budget_micro": { "$ref": "#/components/schemas/MicroAmount" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account": { "get": { "operationId": "getAccount", "tags": [ "account" ], "summary": "Profile/security metadata (self); no password/token hashes", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Account profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "email", "role", "host_enabled", "email_verified", "two_factor_enabled", "auth_method", "step_up_method" ], "properties": { "account_id": { "type": "string" }, "email": { "type": "string", "description": "A wallet-created account without an email has a non-routable placeholder ending in @wallet.placeholder.invalid (RFC 6761)." }, "role": { "enum": [ "renter", "host", "admin" ] }, "host_enabled": { "type": "boolean" }, "email_verified": { "type": "boolean", "description": "Quotes, reservations and funding require a verified email or a wallet-created account; hosting requires a verified email." }, "two_factor_enabled": { "type": "boolean" }, "auth_method": { "enum": [ "session", "api-key" ], "description": "How this request authenticated." }, "step_up_method": { "enum": [ "totp", "password", "wallet", "none" ], "description": "The proof POST /api/v1/account/step-up asks for. wallet is a fresh EIP-4361 signature from the wallet a wallet-created account signs in with." }, "name": { "type": "string", "nullable": true, "description": "Display name from sign-up or the social provider; null when none was given." }, "account_kind": { "enum": [ "human", "agent" ], "description": "Who opened the account: a person, or an agent through self-registration." }, "created_at": { "type": "string", "format": "date-time", "description": "When the account was created (member since)." } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/sessions": { "get": { "operationId": "listSessions", "tags": [ "account" ], "summary": "Session metadata (self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Active sessions." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/sessions/{id}": { "delete": { "operationId": "revokeSession", "tags": [ "account" ], "summary": "Revoke one of the caller's own sessions (self; interactive sessions only)", "description": "Deleting the session row is the revocation. A session the caller does not own is indistinguishable from a missing one (404). API-key callers have no sessions (404).", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Better Auth session id (not a UUID)." } ], "responses": { "204": { "description": "Revoked." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "account" ], "summary": "List API keys (self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "API key metadata; secrets never re-shown.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyView" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createApiKey", "tags": [ "account" ], "summary": "Create API key (self, step-up)", "description": "Label, expiry and explicit renter/host scopes. Secret revealed once; only hash stored. No admin scopes or key-based MFA bypass.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "label", "scopes" ], "properties": { "label": { "type": "string", "minLength": 1 }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "renter", "host" ] } } } } } } }, "responses": { "201": { "description": "API key created; secret returned exactly once.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyView" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "pattern": "^ark_", "description": "The API key. Store it now; it is not shown again." } } } ] } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "tags": [ "account" ], "summary": "Revoke API key (self, step-up)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Revoked." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/integrations/{provider}": { "get": { "operationId": "getIntegration", "tags": [ "account" ], "summary": "Third-party token status (self)", "description": "Whether a per-user token is on file for this provider; never the value.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "huggingface" ] } } ], "responses": { "200": { "description": "Token status.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider", "set", "updated_at" ], "properties": { "provider": { "enum": [ "huggingface" ] }, "set": { "type": "boolean" }, "updated_at": { "oneOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "setIntegration", "tags": [ "account" ], "summary": "Set/replace third-party token (self, step-up)", "description": "Encrypted at rest the same way as an admin secret setting; never re-shown once saved.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "huggingface" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "Token stored." }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "removeIntegration", "tags": [ "account" ], "summary": "Remove third-party token (self, step-up)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "huggingface" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Removed." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/export": { "post": { "operationId": "exportAccount", "tags": [ "account" ], "summary": "Data export (self, recent re-auth)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Export job persisted." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/deletion-request": { "post": { "operationId": "requestAccountDeletion", "tags": [ "account" ], "summary": "Retention-aware deletion request (self, recent re-auth); required ledger evidence preserved under disclosed policy", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Deletion request persisted." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/wallets": { "get": { "operationId": "listWallets", "tags": [ "wallets" ], "summary": "List wallet bindings (verified self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Wallet bindings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WalletBinding" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/wallets/nonce": { "post": { "operationId": "createWalletNonce", "tags": [ "wallets" ], "summary": "SIWE nonce (verified self, re-auth)", "description": "Five-minute single-use nonce with exact origin/URI, chain, issued/expiration time and server-session binding.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Single-use nonce.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "nonce", "expires_at" ], "properties": { "nonce": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/wallets/link": { "post": { "operationId": "linkWallet", "tags": [ "wallets" ], "summary": "Link wallet via SIWE proof (verified self, re-auth)", "description": "Binds chain/address to account; nonce consumed once. UNIQUE(chain_id,address) across accounts.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "chain_id", "address", "siwe_message", "signature" ], "properties": { "chain_id": { "const": 8453 }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "siwe_message": { "type": "string", "minLength": 1 }, "signature": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "Binding created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBinding" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/wallets/{binding_id}": { "delete": { "operationId": "unlinkWallet", "tags": [ "wallets" ], "summary": "Unlink wallet (verified self, re-auth)", "description": "Blocks future use but retains historical attribution and pending-intent versions; old transfers cannot become claimable by another account.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Unlinked." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/funding-intents": { "post": { "operationId": "createFundingIntent", "tags": [ "billing" ], "summary": "Create funding intent (bound wallet owner)", "description": "Chain 8453/USDC to treasury address/token, exact network, expiry and noncustodial-send instructions. No private key collection.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "wallet_binding_id", "amount_micro" ], "properties": { "wallet_binding_id": { "$ref": "#/components/schemas/UUID" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" } } } } } }, "responses": { "201": { "description": "Funding intent.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "intent_id", "chain_id", "token", "treasury_address", "amount_micro", "expires_at", "instructions" ], "properties": { "intent_id": { "$ref": "#/components/schemas/UUID" }, "chain_id": { "const": 8453 }, "token": { "$ref": "#/components/schemas/EvmAddress" }, "treasury_address": { "$ref": "#/components/schemas/EvmAddress" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "instructions": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/funding-intents/{id}": { "get": { "operationId": "getFundingIntent", "tags": [ "billing" ], "summary": "Funding intent state (intent owner)", "description": "Read-only; never claims or credits. While a recorded transfer awaits finality, finalized_block_number is the RPC's finalized head (null when the RPC is unreachable). No time estimate is given.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Funding intent.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "intent_id", "state", "chain_id", "token", "treasury_address", "amount_micro", "tx_hash", "log_index", "block_number", "finalized_block_number", "credited_micro", "exception_reason", "expires_at", "created_at" ], "properties": { "intent_id": { "$ref": "#/components/schemas/UUID" }, "state": { "enum": [ "PENDING", "PENDING_FINALITY", "CONFIRMED", "EXCEPTION" ] }, "chain_id": { "const": 8453 }, "token": { "$ref": "#/components/schemas/EvmAddress" }, "treasury_address": { "$ref": "#/components/schemas/EvmAddress" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "tx_hash": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, { "type": "null" } ] }, "log_index": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "block_number": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ] }, "finalized_block_number": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ] }, "credited_micro": { "description": "Set once the deposit is credited. With state PENDING_FINALITY it was credited before finality (spendable now, withdrawable once final).", "anyOf": [ { "$ref": "#/components/schemas/MicroAmount" }, { "type": "null" } ] }, "exception_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "created_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/funding-intents/{id}/claim": { "post": { "operationId": "claimFundingIntent", "tags": [ "billing" ], "summary": "Claim funding intent (intent owner)", "description": "Verifies ERC20 Transfer sender=bound wallet, recipient=treasury, exact token/chain, successful receipt, canonical block and finalized head; PENDING/CONFIRMED/EXCEPTION. A transfer from a wallet not bound to this account is 403 and records nothing on the intent; a transfer not yet visible is PENDING and records nothing. Provider error pauses credit; never zero balance and never success.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "tx_hash", "log_index" ], "properties": { "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "log_index": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "202": { "description": "Claim state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "intent_id", "state" ], "properties": { "intent_id": { "$ref": "#/components/schemas/UUID" }, "state": { "enum": [ "PENDING", "CONFIRMED", "EXCEPTION" ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing": { "get": { "operationId": "getBalances", "tags": [ "billing" ], "summary": "Balance summary (self/admin); spendable/held/pending/disputed/withdrawable separately, plus 30-day spend and active hold", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USDC", "USDT" ], "default": "USDC" } } ], "responses": { "200": { "description": "Balances.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSet" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing/deposit-address": { "get": { "operationId": "getDepositAddress", "tags": [ "billing" ], "summary": "This account's own deposit address (the same on every listed network, created on first call), plus recent deposits", "description": "Send USDC or USDT, or the network's own coin (ETH, POL, BNB, AVAX), to `address` on any network in `networks`, from anywhere: an exchange or any wallet. No wallet linking and no transaction hash are needed. Each stablecoin transfer is credited exactly once, after that network's finality, 1:1. A native coin is credited in USD at the Chainlink price at finality minus `native.spread_bps`. The address never changes. Funds sent on a network not listed in `networks` are not credited. `deposits` lists recent deposits: SEEN (on chain, waiting for finality; display only), CREDITED, or HELD (arrived but over a balance cap; credited automatically once there is room).", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "The deposit address and recent deposits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } }, "503": { "description": "Deposit addresses are not configured on this server." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing/entries": { "get": { "operationId": "listLedgerEntries", "tags": [ "billing" ], "summary": "Itemized ledger entries (self/admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of ledger entries with immutable external references and evidence links." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing/receipts/{job}": { "get": { "operationId": "getReceipt", "tags": [ "billing" ], "summary": "Itemized invoice/receipt and supplier information for a job (self/admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "job", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Receipt. charge_micro = fee_micro + host_micro, as posted to the ledger.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "state", "machine_rate_micro_per_hour", "platform_fee_bps", "accepted_runtime_ms", "charge_micro", "fee_micro", "host_micro", "funded_budget_micro", "supplier", "operator", "entries" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "state": { "type": "string" }, "machine_rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "platform_fee_bps": { "type": "integer", "minimum": 0 }, "accepted_runtime_ms": { "$ref": "#/components/schemas/DecimalString" }, "charge_micro": { "$ref": "#/components/schemas/MicroAmount" }, "fee_micro": { "$ref": "#/components/schemas/MicroAmount" }, "host_micro": { "$ref": "#/components/schemas/MicroAmount" }, "funded_budget_micro": { "$ref": "#/components/schemas/MicroAmount" }, "supplier": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string" } } }, "operator": { "type": "object", "properties": { "name": { "type": "string" }, "support_email": { "type": "string" } } }, "entries": { "type": "array", "items": { "type": "object", "required": [ "transaction_id", "kind", "external_ref", "at" ], "properties": { "transaction_id": { "type": "string" }, "kind": { "type": "string" }, "external_ref": { "type": "string" }, "at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing/x402/top-up": { "post": { "operationId": "x402TopUp", "tags": [ "billing" ], "summary": "Top up the prepaid balance with an x402 payment (agents)", "description": "x402 v2, scheme exact: an EIP-3009 transferWithAuthorization of native USDC on Base (eip155:8453) straight to the treasury. Without a payment header the answer is 402 with PaymentRequirements (also base64 in the PAYMENT-REQUIRED header). Sign them and repeat the same request with PAYMENT-SIGNATURE (the v1 header name X-PAYMENT is accepted too). The payment itself authorizes the top-up; no Idempotency-Key is needed, and repeating the same payment returns the first result. The credit goes to the API key's account whatever wallet pays, and lands once, after Base finality (state PENDING_FINALITY until then). A 202 means the settlement is broadcast but not mined yet; repeat the same request. 404 while the operator has not enabled x402.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "amount_micro", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/DecimalString" }, "description": "Top-up amount in micro-USDC (\"5000000\" = 5 USDC)." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64 JSON x402 v2 PaymentPayload." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Same as PAYMENT-SIGNATURE (x402 v1 header name)." } ], "responses": { "200": { "description": "Settled on chain and pinned to this account; credited now (CONFIRMED) or after finality (PENDING_FINALITY). PAYMENT-RESPONSE and X-PAYMENT-RESPONSE carry the base64 SettlementResponse.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402TopUp" } } } }, "202": { "description": "Settlement broadcast, not mined yet. Repeat the same request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "state", "tx_hash" ], "properties": { "state": { "enum": [ "SETTLING" ] }, "tx_hash": { "type": "string" }, "retry": { "type": "string" } } } } } }, "402": { "description": "Payment required, or the payment was refused (error names the reason, e.g. invalid_amount, authorization_expired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawals": { "post": { "operationId": "createWithdrawal", "tags": [ "billing" ], "summary": "Withdraw to an address (code; a new address is confirmed by an email link)", "description": "Locked withdrawal intent to a saved address, or, for an address this account never used, a parked request that the emailed link (30 min) queues unchanged. New addresses are refused for 24 h after a password, 2FA or email change. API keys reach saved addresses only, without a code. No spendable credit while a transfer is pending.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" } } } }, "responses": { "202": { "description": "Queued, or waiting for the email link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferAccepted" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawals/code": { "post": { "operationId": "sendWithdrawalCode", "tags": [ "billing" ], "summary": "Email a 6-digit code for one withdrawal or payout (session, no 2FA)", "description": "Bound to kind, network, address, amount and asset; 10 minutes, 5 tries, single use, 5 per hour. 409 for 2FA accounts (use the authenticator).", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kind", "address", "amount_micro" ], "properties": { "kind": { "type": "string", "enum": [ "withdrawal", "payout" ] }, "network": { "type": "string", "enum": [ "base" ] }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] } } } } } }, "responses": { "202": { "description": "Code sent.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sent", "expires_at" ], "properties": { "sent": { "const": true }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawal-addresses": { "get": { "operationId": "listWithdrawalAddresses", "tags": [ "billing" ], "summary": "Saved withdrawal and payout addresses (self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Saved and pending addresses.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalAddress" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "addWithdrawalAddress", "tags": [ "billing" ], "summary": "Save an address ahead of time (session; confirmed by email link)", "description": "2FA accounts also send their authenticator `code`. Needed before API-key withdrawals to a new address. Wallet-only accounts and API keys cannot add addresses.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "address" ], "properties": { "network": { "type": "string", "enum": [ "base" ] }, "address": { "$ref": "#/components/schemas/EvmAddress" }, "label": { "type": "string", "minLength": 1, "maxLength": 40 }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } } } } } }, "responses": { "202": { "description": "Link sent (or already saved).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "state", "address_id" ], "properties": { "state": { "type": "string", "enum": [ "AWAITING_EMAIL_CONFIRMATION", "SAVED" ] }, "address_id": { "$ref": "#/components/schemas/UUID" }, "confirmation_id": { "$ref": "#/components/schemas/UUID" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawal-addresses/{id}": { "delete": { "operationId": "removeWithdrawalAddress", "tags": [ "billing" ], "summary": "Remove a saved address (self)", "description": "Bumps its version; an unsigned transfer to it is no longer paid automatically.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "removed" ], "properties": { "removed": { "const": true } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawal-addresses/confirm": { "post": { "operationId": "confirmWithdrawalAddress", "tags": [ "billing" ], "summary": "Open the emailed link (no sign-in; the token is the proof)", "description": "Confirms the address and queues the parked withdrawal or payout exactly as requested. Idempotent. Refused after 30 minutes or after a credential change.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } } } } }, "responses": { "200": { "description": "Confirmed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "confirmed", "kind", "address_id", "intent_id" ], "properties": { "confirmed": { "const": true }, "kind": { "type": "string", "enum": [ "withdrawal", "payout", "address" ] }, "address_id": { "$ref": "#/components/schemas/UUID" }, "intent_id": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/enrollment-tokens": { "post": { "operationId": "createEnrollmentToken", "tags": [ "hosts" ], "summary": "Host enrollment token (verified host account)", "description": "One-use 10-minute token plus signed release URL/digest and preflight steps. Rate-limited independently.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Enrollment material.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "expires_at", "release_url", "release_digest", "preflight_steps" ], "properties": { "token": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "release_url": { "type": "string" }, "release_digest": { "$ref": "#/components/schemas/Sha256Hash" }, "preflight_steps": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agents/accounts/challenge": { "post": { "operationId": "createAgentAccountChallenge", "tags": [ "agents" ], "summary": "Step 1 of agent self-registration; an EIP-4361 message to sign (unauthenticated)", "description": "Returns a server-written Sign-In with Ethereum (EIP-4361) message for this address: this deployment's domain and URI, Base (chain 8453), a single-use nonce and a five-minute expiry. Its statement carries the Terms version the agent accepts by signing. Sign it exactly as returned (EIP-191 personal_sign) with the wallet's key. EOA wallets only. Rate-limited per source address and per wallet. Not /api/v1/agents/enroll, which enrolls host machines.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } } } }, "responses": { "200": { "description": "The message to sign.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "message", "expires_at", "terms_version", "terms_url" ], "properties": { "message": { "type": "string" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "terms_version": { "type": "string", "example": "rental-v1" }, "terms_url": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/agents/accounts": { "post": { "operationId": "registerAgentAccount", "tags": [ "agents" ], "summary": "Step 2 of agent self-registration; the signed message returns an agent account and an API key (unauthenticated)", "description": "Verifies the signed challenge (single use, unexpired, byte-for-byte the message the server wrote, signed by its address) and opens an account tagged account_kind agent, with the wallet as its verified linked wallet and payout destination. Returns an API key with the renter scope (add \"host\" to scopes to host), shown once. The same wallet again returns the same account (200) and a new key, only with a fresh signature. There is no free credit: fund the account (POST /api/v1/funding-intents) before renting. Refused: a replayed, expired or tampered message (401); a wallet linked to or unlinked from another account, or an account with an authenticator app (409); a suspended account's wallet (403). Rate-limited per source address and per wallet (429). Audited.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "message", "signature", "agent" ], "properties": { "message": { "type": "string", "maxLength": 2048, "description": "The challenge message", "exactly as returned.": null }, "signature": { "type": "string", "maxLength": 1024, "description": "0x-prefixed EIP-191 signature." }, "agent": { "type": "object", "additionalProperties": false, "description": "Self-declared and unverified; shown to operators, never used for authorization.", "required": [ "name", "vendor" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "vendor": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Who made the agent or its model, e.g. \"grok\"." }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator_contact": { "type": "string", "minLength": 1, "maxLength": 254 }, "homepage": { "type": "string", "format": "uri", "maxLength": 2048 } } }, "scopes": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "string", "enum": [ "renter", "host" ] }, "default": [ "renter" ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/AgentAccountRegistered" }, "201": { "$ref": "#/components/responses/AgentAccountRegistered" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/pairings": { "post": { "operationId": "createHostPairing", "tags": [ "hosts" ], "summary": "Open a host pairing (installer; unauthenticated)", "description": "Called by the one-line installer (`curl -fsSL https://amplerun.com/host | sudo bash`). Returns a short user_code for a person to approve on /pair and a poll_secret only the installer holds; only their hashes are stored. Expires after 10 minutes. The code alone never yields a token. Rate-limited per source address.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "summary" ], "properties": { "summary": { "type": "object", "additionalProperties": false, "description": "What the installer reports about the machine. Unverified; shown to the approver.", "required": [ "hostname", "gpus" ], "properties": { "hostname": { "type": "string", "maxLength": 253 }, "os": { "type": "string", "maxLength": 100 }, "gpus": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "vram_mib": { "type": "integer", "minimum": 0 } } } } } } } } } } }, "responses": { "201": { "description": "Pairing opened.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "pairing_id", "user_code", "poll_secret", "expires_at", "interval", "verification_uri", "verification_uri_complete" ], "properties": { "pairing_id": { "$ref": "#/components/schemas/UUID" }, "user_code": { "type": "string", "description": "XXXX-XXXX from an alphabet without look-alike characters" }, "poll_secret": { "type": "string", "description": "Shown once; needed to poll." }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "interval": { "type": "integer", "description": "Seconds between polls." }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/pairings/lookup": { "post": { "operationId": "lookupHostPairing", "tags": [ "hosts" ], "summary": "Show the machine behind a pairing code (verified session)", "description": "Returns the installer's report for a pending, unexpired code. Same session and guessing rules as approve; a wrong code counts as a miss (10 per hour per account and per address).", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_code" ], "properties": { "user_code": { "type": "string", "maxLength": 32 } } } } } }, "responses": { "200": { "description": "Pending pairing.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "summary", "expires_at" ], "properties": { "summary": { "type": "object" }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/pairings/approve": { "post": { "operationId": "approveHostPairing", "tags": [ "hosts" ], "summary": "Approve a pairing code (verified session, or an API key with the host scope)", "description": "The consent step of one-line host onboarding. Applies the same hosting rules as createEnrollmentToken (verified email, host scope, admin block, new-host cap; the first use turns hosting on). go_live (default true) lists the machine's seeded offer, unverified, on its first healthy heartbeat through the same path as listMachine with x-accept-unverified, paid-admission guard included. Audited. Wrong codes are limited as in lookup.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_code" ], "properties": { "user_code": { "type": "string", "maxLength": 32 }, "go_live": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Approved.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "approved", "go_live", "summary" ], "properties": { "approved": { "const": true }, "go_live": { "type": "boolean" }, "summary": { "type": "object" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/pairings/poll": { "post": { "operationId": "pollHostPairing", "tags": [ "hosts" ], "summary": "Poll a pairing (installer; needs poll_secret)", "description": "pending, expired, approved (once, with a fresh single-use 10-minute enrollment token for POST /api/v1/agents/enroll; the pairing is consumed in the same transaction after the approver's hosting rules are re-checked), then consumed (no token; the enrolled machine's Go-live state). A wrong pairing_id or poll_secret is 404.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "pairing_id", "poll_secret" ], "properties": { "pairing_id": { "$ref": "#/components/schemas/UUID" }, "poll_secret": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Pairing state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "expired", "approved", "consumed" ] }, "enrollment_token": { "type": "string", "description": "Only with status approved", "exactly once.": null }, "expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "go_live": { "type": "boolean" }, "machine": { "type": "object", "nullable": true, "required": [ "machine_id", "live", "error" ], "properties": { "machine_id": { "$ref": "#/components/schemas/UUID" }, "live": { "type": "string", "enum": [ "waiting", "live", "failed", "off" ] }, "error": { "type": "string", "nullable": true } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines": { "get": { "operationId": "listMachines", "tags": [ "hosts" ], "summary": "List own machines (host owner/admin)", "description": "Each row carries the machine's hardware specs and its current offer, so a console can render a fleet table without one detail fetch per machine. Specs are read from the same source the public catalog reads (`manifest->devices`). A spec nobody measured is `null` — never 0 and never an empty string; `ram_bytes`, `disk_bytes` and `region` are not measured anywhere today and are therefore null in practice. `current_offer` is null when the machine has no published offer version, which is a real state (a machine mid-onboarding), not a free listing.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of machine summaries.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "machine_id", "state", "manifest_hash", "fence", "version", "last_healthy_at", "gpu_model", "gpu_count", "vram_bytes", "ram_bytes", "disk_bytes", "region", "current_offer" ], "properties": { "machine_id": { "$ref": "#/components/schemas/UUID" }, "state": { "type": "string", "enum": [ "UNQUALIFIED", "AVAILABLE", "ALLOCATED", "CLEANING", "DRAINING", "UNLISTED", "QUARANTINED" ] }, "manifest_hash": { "type": "string" }, "fence": { "$ref": "#/components/schemas/DecimalString" }, "version": { "$ref": "#/components/schemas/DecimalString" }, "last_healthy_at": { "oneOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" }, { "type": "null" } ] }, "gpu_inventory": { "type": "array", "description": "Per-device discovery; not qualification. Shared-memory graphics remain distinct.", "items": { "type": "object", "additionalProperties": false, "required": [ "pci_address", "vendor", "model", "memory_bytes", "memory_class" ], "properties": { "pci_address": { "type": "string" }, "vendor": { "type": "string" }, "model": { "type": "string", "nullable": true }, "memory_bytes": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "memory_class": { "type": "string", "enum": [ "dedicated", "shared", "unknown" ] } } } }, "gpu_model": { "type": "string", "nullable": true }, "gpu_count": { "type": "integer", "minimum": 1, "nullable": true }, "vram_bytes": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "ram_bytes": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "disk_bytes": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "region": { "type": "string", "nullable": true }, "current_offer": { "nullable": true, "type": "object", "additionalProperties": false, "required": [ "offer_version", "rate_micro_per_hour", "state" ], "properties": { "offer_version": { "$ref": "#/components/schemas/DecimalString" }, "rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "state": { "type": "string", "enum": [ "listed", "unlisted", "draining" ] } } } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}": { "get": { "operationId": "getMachine", "tags": [ "hosts" ], "summary": "Machine detail: compatibility findings, current offer/job, observed metrics, drain state (host owner/admin)", "description": "Includes `telemetry`: the latest agent-reported sample plus `observed_at`, `age_s` and `boot_id`, or null when nothing was ever reported. Telemetry is evidence only and never influences admission, qualification, billing or job state. A measurement the host could not take is ABSENT from the object — it is never rendered as 0 and never carried over from an earlier sample, so a consumer must age it via `age_s` and show `unknown` when stale.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Machine detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepts_custom_images": { "type": "boolean", "description": "The host's opt-in to renter-supplied public images on this machine (default false)." }, "tier": { "type": "string", "enum": [ "container", "inference" ], "description": "Tier A (renter containers) or Tier B (managed inference), set at enrollment." }, "host_mode": { "nullable": true, "description": "D-22 host mode as the last heartbeat reported it; null until one does.", "type": "object", "properties": { "mode": { "type": "string", "nullable": true, "enum": [ "dedicated", "idle", "colisted" ] }, "offerable": { "type": "boolean", "nullable": true }, "reasons": { "type": "array", "items": { "type": "string" } }, "observed_at": { "type": "string" } } }, "kernel_driver_runtime": { "type": "string", "nullable": true, "description": "Kernel/driver/runtime triple from the manifest, e.g. linux-6.8/nvidia-560.35/cuda-12.6." }, "recent_jobs": { "type": "array", "description": "The machine's latest 20 rentals, newest first. ended_at is null while a rental is open.", "items": { "type": "object", "required": [ "job_id", "state", "started_at", "ended_at", "rate_micro_per_hour" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "state": { "type": "string" }, "started_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "ended_at": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339Utc" } ], "nullable": true }, "rate_micro_per_hour": { "type": "string" }, "ready": { "type": "boolean", "description": "False when the host never reached READY (a refused START): nothing ran and nothing was billed." }, "billed_ms": { "type": "string", "description": "Metered (billed) runtime in ms, from READY." }, "earned_micro": { "type": "string", "description": "The host's posted share for this rental, micro-USD." } } } }, "listing_blockers": { "type": "array", "items": { "type": "string" } }, "market_price": { "nullable": true, "type": "object", "description": "D-35 suggested listing price: the market price a renter pays for ONE of this GPU for one hour. basis amplerun = AmpleRun's own listed offers of this model (at least 3); otherwise basis reference = a hand-curated table of official public list prices, each with its page and the date it was read (upper side, p75); otherwise basis throughput = each reference row of the same class (consumer or datacenter) turned into the price giving this GPU the same tokens per dollar, from memory bandwidth (LLM token generation is memory-bound), and the p75 of those. Renters pay the listed price (the 10% commission comes out of it), so the suggestion is the market price itself. null when neither exists. A suggestion only: the host sets its own price.", "required": [ "gpu_model", "basis", "median_micro_per_gpu_hour", "sample_size", "sources" ], "properties": { "gpu_model": { "type": "string", "description": "Canonical GPU name the prices were matched to." }, "basis": { "enum": [ "amplerun", "reference", "throughput" ] }, "median_micro_per_gpu_hour": { "type": "string", "description": "Decimal string, micro-USD per GPU per hour." }, "sample_size": { "type": "integer", "description": "Listings or reference prices behind the median." }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label", "url", "accessed" ], "properties": { "label": { "type": "string" }, "url": { "type": "string", "description": "Page where the price can be checked." }, "accessed": { "type": "string", "description": "YYYY-MM-DD the price was read." } } } }, "estimate": { "nullable": true, "type": "object", "description": "ESTIMATED from memory bandwidth, not measured on this machine. null when the GPU's bandwidth is unknown.", "required": [ "tok_s_8b", "micro_per_million_tokens", "fits_up_to_b_params" ], "properties": { "tok_s_8b": { "type": "number", "description": "Estimated generation speed on an 8B Q4_K_M model, tokens/s." }, "micro_per_million_tokens": { "type": "string", "description": "The per-GPU-hour price per 1M generated tokens at that speed, micro-USD." }, "fits_up_to_b_params": { "type": "integer", "description": "Largest model that fits, billions of parameters at Q4." } } } } }, "auto_qualify": { "type": "object", "description": "The automatic machine test: the worker queues it while the agent heartbeats, retries failures with backoff, and admits a passed machine with a listed offer. reason is set for retrying and needs_attention.", "required": [ "state", "reason" ], "properties": { "state": { "type": "string", "enum": [ "testing", "passed", "retrying", "needs_attention", "waiting" ] }, "reason": { "type": "string", "nullable": true } } }, "telemetry": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TelemetrySample" }, { "type": "object", "required": [ "observed_at", "age_s", "boot_id" ], "properties": { "observed_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "age_s": { "type": "integer", "minimum": 0 }, "boot_id": { "type": "string" } } } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "removeMachine", "tags": [ "hosts" ], "summary": "Remove an idle machine registration, preserving history", "description": "Revokes agent credentials and unlists offers. Active rentals or incomplete cleanup return 409. Re-enrollment is required to reconnect.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "204": { "description": "Registration removed; history retained." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/telemetry": { "get": { "operationId": "getMachineTelemetry", "tags": [ "hosts" ], "summary": "Rolling telemetry history in 5-minute buckets (host owner/admin)", "description": "Min/avg/max per measured field per 5-minute bucket, for sparklines. Host owner only: a non-owner receives 404, never 403, so machine existence never leaks. History is retained for 48 h and pruned by the worker cleanup task; a `window` longer than the retention is refused rather than silently clamped. A field that was never measured in a bucket is absent, and a bucket's `samples` count states how much evidence backs it.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "name": "window", "in": "query", "required": false, "description": "Lookback as s|m|h (default 6h, at most the retention window).", "schema": { "type": "string", "pattern": "^[1-9][0-9]*[smh]$" } } ], "responses": { "200": { "description": "Telemetry history buckets, oldest first.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "machine_id", "window_s", "bucket_s", "retention_s", "buckets" ], "properties": { "machine_id": { "$ref": "#/components/schemas/UUID" }, "window_s": { "type": "integer", "minimum": 1 }, "bucket_s": { "type": "integer", "enum": [ 300 ] }, "retention_s": { "type": "integer", "enum": [ 172800 ] }, "buckets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "bucket", "samples", "devices" ], "properties": { "bucket": { "$ref": "#/components/schemas/Rfc3339Utc" }, "samples": { "type": "integer", "minimum": 1 }, "devices": { "type": "array", "items": { "type": "object", "required": [ "pci_address" ], "properties": { "pci_address": { "type": "string" }, "temperature_c": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "utilization_pct": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "power_watts": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "fan_pct": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "memory_used_bytes": { "$ref": "#/components/schemas/TelemetryAmountSummary" }, "unified_memory_used_bytes": { "$ref": "#/components/schemas/TelemetryAmountSummary" } } } }, "host": { "type": "object", "properties": { "cpu_utilization_pct": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "load1": { "$ref": "#/components/schemas/TelemetryNumberSummary" }, "memory_used_bytes": { "$ref": "#/components/schemas/TelemetryAmountSummary" }, "disk_free_bytes": { "$ref": "#/components/schemas/TelemetryAmountSummary" }, "uptime_s": { "$ref": "#/components/schemas/TelemetryAmountSummary" } } } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/offer": { "post": { "operationId": "publishOffer", "tags": [ "hosts" ], "summary": "Publish versioned future offer (host owner)", "description": "Aggregate rate, included limits, available_from/available_until, optional maintenance window, expected_version. Versioned future offer only; never alters a running price.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rate_micro_per_hour", "included_quotas", "available_from", "available_until", "expected_version" ], "properties": { "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" } } } }, "expected_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Offer version committed with new offer_version." }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "editOffer", "tags": [ "hosts" ], "summary": "Edit the listing by publishing the next offer version (host owner)", "description": "The host console's listing editor. Despite the verb this is APPEND-ONLY: the next `version` is inserted and no existing row is ever rewritten, so a live job keeps the rate its quote snapshotted — the quote remains the only price authority. `expected_version` is compare-and-swapped against the CURRENT offer version (not the machine version the POST form uses); a race answers 409 with `error.code = VERSION_CONFLICT` and a sibling `current` block so the editor can show what changed instead of overwriting it. `listing_expires_at` has no column of its own and is FOLDED onto `available_until` (the earlier of the two wins — `available_until` already means \"bookable until\", which is what the catalog filters on); the response echoes the stored value. `min_duration_s` and `max_duration_s` are accepted but NOT stored, because no per-offer duration bound exists in the schema and nothing at quote time would enforce one; they are named back to the caller in `ignored_fields` rather than silently dropped. A publish that would retract availability a live job is already holding is refused 409 CONFLICT.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_version", "rate_micro_per_hour", "included_disk_gib", "included_egress_gib", "available_from", "available_until" ], "properties": { "expected_version": { "$ref": "#/components/schemas/DecimalString" }, "rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "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" }, "listing_expires_at": { "$ref": "#/components/schemas/Rfc3339Utc" }, "min_duration_s": { "type": "integer", "minimum": 0, "description": "Accepted, never stored; reported in ignored_fields." }, "max_duration_s": { "type": "integer", "minimum": 0, "description": "Accepted, never stored; reported in ignored_fields." }, "availability_class": { "$ref": "#/components/schemas/AvailabilityClass", "description": "D-22. Omitted keeps the current version's class. interruptible needs preemption_notice_s; an idle or co-listed host can rent only interruptible offers. 409 until the D-22 migration is released." }, "preemption_notice_s": { "type": "integer", "minimum": 0, "maximum": 3600, "description": "D-22. Required for interruptible, refused for dedicated; omitted keeps the current value." } } } } } }, "responses": { "202": { "description": "Next offer version published.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "offer_id", "offer_version", "state", "rate_micro_per_hour", "included_disk_gib", "included_egress_gib", "available_from", "available_until", "ignored_fields" ], "properties": { "offer_id": { "$ref": "#/components/schemas/UUID" }, "offer_version": { "$ref": "#/components/schemas/DecimalString" }, "state": { "type": "string", "enum": [ "listed", "unlisted", "draining" ] }, "rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "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" }, "availability_class": { "$ref": "#/components/schemas/AvailabilityClass" }, "preemption_notice_s": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 3600 }, { "type": "null" } ] }, "ignored_fields": { "type": "array", "description": "Request fields accepted by the schema but deliberately not stored.", "items": { "type": "string" } } } } } } }, "409": { "description": "Offer version race (`VERSION_CONFLICT`, with `current`) or a live job whose availability the change would retract (`CONFLICT`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "VERSION_CONFLICT", "CONFLICT", "IDEMPOTENCY_CONFLICT" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "request_id": { "$ref": "#/components/schemas/UUID" } } }, "current": { "type": "object", "description": "Present only for VERSION_CONFLICT — the listing as it now stands.", "additionalProperties": false, "required": [ "offer_version", "rate_micro_per_hour", "available_until" ], "properties": { "offer_version": { "$ref": "#/components/schemas/DecimalString" }, "rate_micro_per_hour": { "$ref": "#/components/schemas/MicroAmount" }, "available_until": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/earnings": { "get": { "operationId": "getMachineEarnings", "tags": [ "hosts" ], "summary": "Per-machine earnings day-series (host owner)", "description": "The account-wide `/hosts/earnings` day-series narrowed to one machine and attributed through `jobs.machine_id`, in the identical shape so one chart renders both. Ledger-derived only: every bar links back to `journal_lines` on `host_payable:` for jobs that ran on this machine, and the series reconciles exactly to those rows. `paid_micro` is zero throughout, because payout settlements carry no `job_id` and belong to the account rather than to any one machine — attributing them would double-count a payout across the fleet. A non-owner receives 404, never 403, so machine existence never leaks. A malformed `window` is refused rather than silently defaulted.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "name": "window", "in": "query", "required": false, "description": "Trailing window as d (default 30d, 1..365).", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,2}d$" } } ], "responses": { "200": { "description": "Daily earnings bars for this machine, oldest first.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "window_days", "from", "to", "days" ], "properties": { "window_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "$ref": "#/components/schemas/Rfc3339Utc" }, "to": { "$ref": "#/components/schemas/Rfc3339Utc" }, "days": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "day", "earned_micro", "fee_micro", "paid_micro", "rental_count" ], "properties": { "day": { "type": "string", "description": "UTC calendar day, YYYY-MM-DD" }, "earned_micro": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "fee_micro": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "paid_micro": { "$ref": "#/components/schemas/MicroAmount" }, "rental_count": { "type": "integer" } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/list": { "post": { "operationId": "listMachineForRent", "tags": [ "hosts" ], "summary": "List machine (host owner); admission checks apply", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Listing admitted or rejected with findings." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/drain": { "post": { "operationId": "drainMachine", "tags": [ "hosts" ], "summary": "Drain machine (host owner); stops new bookings, never kills an active job or retrieval cleanup", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "DRAINING." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/unlist": { "post": { "operationId": "unlistMachine", "tags": [ "hosts" ], "summary": "Unlist idle offer (host owner); never kills an active job or retrieval cleanup", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "UNLISTED." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/nettest": { "post": { "operationId": "queueMachineNettest", "tags": [ "hosts" ], "summary": "Re-run the network measurement (host owner/admin); queues a NETTEST command, result lands with the agent's next contact", "description": "netfacts lane. The agent measures download/upload Mbps and latency from the HOST network namespace against a public endpoint (bounded 30 s) and answers with a machine.nettest receipt that updates the machine's net facts. 202 = queued, never the measurement itself.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Queued; body carries machine_id, command_id, state=QUEUED." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/custom-images": { "put": { "operationId": "setMachineCustomImages", "tags": [ "hosts" ], "summary": "Opt this machine in or out of renter-supplied public images (host owner)", "description": "Default false: a machine that never opted in never receives a custom image. Opting in is 409 while the marketplace has custom images disabled; opting out always works and wins any reservation in flight. Custom images still run under the mandatory launch profile. Each change is audited.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "accept" ], "properties": { "accept": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Current opt-in.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "machine_id", "accepts_custom_images" ], "properties": { "machine_id": { "$ref": "#/components/schemas/UUID" }, "accepts_custom_images": { "type": "boolean" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/earnings": { "get": { "operationId": "getHostEarnings", "tags": [ "hosts" ], "summary": "Earnings (host owner): earned, disputed, payable, requested, settled; gross vs snapshotted fee; no utilization guess", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USDC", "USDT" ], "default": "USDC" } } ], "responses": { "200": { "description": "Earnings breakdown.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "earned_micro", "disputed_micro", "payable_micro", "requested_micro", "settled_micro", "gross_micro", "fee_micro", "fee_bps", "window_days", "from", "to", "days" ], "properties": { "earned_micro": { "$ref": "#/components/schemas/MicroAmount" }, "disputed_micro": { "$ref": "#/components/schemas/MicroAmount" }, "payable_micro": { "$ref": "#/components/schemas/MicroAmount" }, "requested_micro": { "$ref": "#/components/schemas/MicroAmount" }, "settled_micro": { "$ref": "#/components/schemas/MicroAmount" }, "gross_micro": { "$ref": "#/components/schemas/MicroAmount" }, "fee_micro": { "$ref": "#/components/schemas/MicroAmount" }, "fee_bps": { "type": "integer" }, "window_days": { "type": "integer" }, "from": { "$ref": "#/components/schemas/Rfc3339Utc" }, "to": { "$ref": "#/components/schemas/Rfc3339Utc" }, "days": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "day", "earned_micro", "fee_micro", "paid_micro", "rental_count" ], "properties": { "day": { "type": "string", "description": "UTC calendar day, YYYY-MM-DD" }, "earned_micro": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "fee_micro": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "paid_micro": { "$ref": "#/components/schemas/MicroAmount" }, "rental_count": { "type": "integer" } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/market": { "get": { "operationId": "getHostMarket", "tags": [ "hosts" ], "summary": "Market stats (host): per-GPU-model supply, listed-rate band, fill rate and time-to-first-rental — aggregate only", "description": "Our own marketplace, never a competitor's. Aggregate only: no machine id,\nhost id, offer id or any individual host's rate is ever returned — the\nonly rate values that escape are the p10/median/p90 band of a bucket of\nat least `min_sample_size` listed machines, plus the CALLER's own median\nlisted rate (`your_rate_micro`). Below the threshold a bucket reports its\n`sample_size` with every metric null; a median is never computed from a\nhandful of observations. `median_time_to_first_rental_s` has its own\nsample gate (`rental_sample_size`), because a model can be widely listed\nand barely rented. Window is half-open UTC `[from, to)`.\n", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "gpu_model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact manifest GPU model to restrict to." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,2}d$", "default": "30d" }, "description": "Trailing window, e.g. 30d (1..365); anything else is 422." } ], "responses": { "200": { "description": "Per-model market aggregates.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "window_days", "from", "to", "min_sample_size", "models" ], "properties": { "window_days": { "type": "integer" }, "from": { "$ref": "#/components/schemas/Rfc3339Utc" }, "to": { "$ref": "#/components/schemas/Rfc3339Utc" }, "min_sample_size": { "type": "integer", "description": "Observations required before any metric is reported." }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "gpu_model", "sample_size", "listed_gpus", "allocated_gpus", "utilization_pct", "rate_micro", "fill_rate_pct", "rental_sample_size", "median_time_to_first_rental_s", "your_rate_micro" ], "properties": { "gpu_model": { "type": "string" }, "sample_size": { "type": "integer", "description": "Listed machines of this model; the denominator of every metric below." }, "listed_gpus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "allocated_gpus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "utilization_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Floored allocated/listed GPU percent." }, "rate_micro": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "p10_micro", "median_micro", "p90_micro" ], "properties": { "p10_micro": { "$ref": "#/components/schemas/MicroAmount" }, "median_micro": { "$ref": "#/components/schemas/MicroAmount" }, "p90_micro": { "$ref": "#/components/schemas/MicroAmount" } } }, { "type": "null" } ] }, "fill_rate_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Floored share of listed machines rented at least once in the window." }, "rental_sample_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "median_time_to_first_rental_s": { "anyOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "your_rate_micro": { "anyOf": [ { "$ref": "#/components/schemas/MicroAmount" }, { "type": "null" } ], "description": "The caller's own median listed rate for this model." } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/payouts": { "post": { "operationId": "requestPayout", "tags": [ "hosts" ], "summary": "Request a payout to an address (host owner; same model as withdrawals)", "description": "Payout intent locked against payable, to a saved address, or parked until the emailed link confirms a new one. Sessions confirm with `code` (POST /api/v1/withdrawals/code with kind=payout, or the authenticator); API keys reach saved addresses only.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" } } } }, "responses": { "202": { "description": "Queued, or waiting for the email link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferAccepted" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tickets": { "get": { "operationId": "listTickets", "tags": [ "support" ], "summary": "List own tickets (opener); cursor paged, ordered by id", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of ticket summaries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "ticket_id", "category", "state", "job_id", "created_at" ], "properties": { "ticket_id": { "$ref": "#/components/schemas/UUID" }, "category": { "type": "string" }, "state": { "type": "string" }, "job_id": { "anyOf": [ { "$ref": "#/components/schemas/UUID" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Rfc3339Utc" } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createTicket", "tags": [ "support" ], "summary": "Open support ticket (participant/admin); secrets redacted, ownership checked", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "category", "text" ], "properties": { "category": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 }, "job_id": { "$ref": "#/components/schemas/UUID" }, "payment_reference": { "type": "string" } } } } } }, "responses": { "201": { "description": "Ticket created." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tickets/{id}": { "get": { "operationId": "getTicket", "tags": [ "support" ], "summary": "Ticket thread (participant/admin); participants see only their own permitted thread", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Ticket with messages. Each message carries author (you, support, customer or host, relative to the reader); can_reply is true while the case is open." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tickets/{id}/messages": { "post": { "operationId": "addTicketMessage", "tags": [ "support" ], "summary": "Append message (participant/admin)", "description": "The opener, the rental's host, or an admin (a support reply) may post to an OPEN case; anyone else gets 403 and a closed case 409.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "Message appended." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/users": { "get": { "operationId": "adminListUsers", "tags": [ "admin" ], "summary": "Admin user view (Admin); immutable references", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent", "human" ] }, "description": "Only accounts an AI agent registered for itself (agent), or the rest (human)." } ], "responses": { "200": { "description": "Filtered operational view. Each row carries account_kind and, for agents, the self-declared agent_profile." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/users/{id}": { "get": { "operationId": "adminGetUser", "tags": [ "admin" ], "summary": "User detail (Admin) — role, capabilities, MFA, linked providers, wallets, sessions, live rentals", "description": "Everything that decides what this account can do right now, on one response. Credential material is never projected: no password hash, no TOTP secret or backup codes, no API key hash, no session token. A linked sign-in provider shows its name and when it was linked, nothing else. `user.version` is the expected-version token for the actions endpoint.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The account's current authority and state." }, "404": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/users/{id}/actions": { "post": { "operationId": "adminUserAction", "tags": [ "admin" ], "summary": "User management command (Admin+step-up); typed reason, expected version, audit event", "description": "One of five commands. Every one requires an admin session with an enrolled TOTP factor, a fresh `admin-sensitive` step-up grant, an Idempotency-Key, a typed reason and the `expected_version` read from GET /api/v1/admin/users/{id}. A stale version is 409 STALE_VERSION and writes nothing. There is no balance action here and there must never be one.\n\n`set_role` and `set_suspension` are refused with 409 CONFLICT when they would leave the system with zero admins; the check locks the admin set inside the transaction, so two demotions racing cannot both succeed.\n\n`set_suspension` blocks sign-in and every API key on the next request and stops new admissions for the account, but never cancels a running rental: it keeps metering and billing to funded expiry or stop. `reset_mfa` clears the enrolment and every session so the user must re-enrol; it never reveals or sets a secret.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action", "role", "reason", "expected_version" ], "properties": { "action": { "type": "string", "enum": [ "set_role" ] }, "role": { "type": "string", "enum": [ "renter", "host", "admin" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "expected_version": { "type": "string", "minLength": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "enabled", "reason", "expected_version" ], "properties": { "action": { "type": "string", "enum": [ "set_host_capability" ] }, "enabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "expected_version": { "type": "string", "minLength": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "suspended", "reason", "expected_version" ], "properties": { "action": { "type": "string", "enum": [ "set_suspension" ] }, "suspended": { "type": "boolean" }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "expected_version": { "type": "string", "minLength": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "reason", "expected_version" ], "properties": { "action": { "type": "string", "enum": [ "revoke_sessions", "reset_mfa" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 }, "expected_version": { "type": "string", "minLength": 1 } } } ] } } } }, "responses": { "200": { "description": "Applied. Returns the new version, what changed and the stated consequence." }, "409": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/machines": { "get": { "operationId": "adminListMachines", "tags": [ "admin" ], "summary": "Admin machine view (Admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/jobs": { "get": { "operationId": "adminListJobs", "tags": [ "admin" ], "summary": "Admin job view (Admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/ledger": { "get": { "operationId": "adminListLedger", "tags": [ "admin" ], "summary": "Admin ledger view (Admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/payouts": { "get": { "operationId": "adminListPayouts", "tags": [ "admin" ], "summary": "Admin payout and withdrawal view (Admin); rows carry kind, and unsigned requests the automatic path holds carry hold_code/hold_reason", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/tickets": { "get": { "operationId": "adminListTickets", "tags": [ "admin" ], "summary": "Admin ticket view (Admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/audit": { "get": { "operationId": "adminListAudit", "tags": [ "admin" ], "summary": "Admin audit view (Admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/reconciliation": { "get": { "operationId": "adminGetReconciliation", "tags": [ "admin" ], "summary": "Admin reconciliation view (Admin); unexplained differences >0 micro pause new paid admissions/payouts", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Reconciliation status; stale RPC yields UNAVAILABLE without overwriting prior confirmed figures." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/analytics": { "get": { "operationId": "adminGetAnalytics", "tags": [ "admin" ], "summary": "Admin analytics (Admin); committed capacity, paid time, GMV, fees, costs, refunds and repeat users separated; unavailable inputs stay null", "description": "Read-only. Adds daily UTC series for the range (signups, active users, rentals, GMV, fees, host earnings, deposits by rail, paid transfers, admitted machines), totals against the previous period, the signup funnel, top renters and hosts with masked emails, and live counts. Series rows and totals also carry `gmv_net_micro` (customer credit debits less refund-reversal credits) and `fees_net_micro` (platform fee credits less debits) over journal kinds charge and refund_reversal, stablecoin assets only, decimal strings in micro-units. `attribution` groups signups, depositors and the first credited stablecoin deposit by ref and by utm_content. Admin accounts and the ATTRIBUTION_EXCLUDE list are left out. Null when the report cannot be read. `paid_time.paid_runtime_ms` sums accepted runtime of finished (CLOSED) and in-flight jobs; admitted capacity stops at `retired_at` for retired machines.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } } ], "responses": { "200": { "description": "Analytics." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/status": { "get": { "operationId": "adminGetStatus", "tags": [ "admin" ], "summary": "Admin status bar (Admin); admissions, reconciliation, worker heartbeat age and RPC reachability", "description": "Read-only. Each source is probed independently; a source that cannot be read reports state \"unknown\" — never a healthy default and never a stale value presented as fresh. The worker staleness threshold is the same one /api/v1/health/ready applies.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Four independent health blocks", "each with its own state and observation.": null }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/search": { "get": { "operationId": "adminSearch", "tags": [ "admin" ], "summary": "Resolve a record id (Admin)", "description": "Exact whole-id equality only — no prefix, wildcard or fuzzy match, so the endpoint cannot be walked to enumerate records. Every miss returns one identical NOT_FOUND message regardless of which kind was searched.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A complete record id." } ], "responses": { "200": { "description": "The resolved kind", "id and admin href.": null }, "404": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/treasury": { "get": { "operationId": "adminGetTreasury", "tags": [ "admin" ], "summary": "Treasury vs liabilities (Admin)", "description": "Aggregates over the immutable journal. Money is bigint decimal strings end to end. A group whose inputs are unavailable is null, never zero. Read-only; no per-account detail is projected.", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Treasury asset", "customer/host liabilities": null, "platform fees and refund totals.": null }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/incidents": { "get": { "operationId": "adminListIncidents", "tags": [ "admin" ], "summary": "Admin incident view (Admin); dispatched alerts with their transport acknowledgement", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Filtered operational view." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/machines/{id}/evidence": { "get": { "operationId": "adminGetMachineEvidence", "tags": [ "admin" ], "summary": "Qualification evidence and manifest drift for a machine (Admin)", "description": "The qualification records an admission decision was made on, plus the drift between the running manifest hash and the qualified one. With no qualification record, drifted is null (unknown), never false.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Machine facts", "drift verdict and the qualification tuples.": null }, "404": { "$ref": "#/components/responses/Error" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/templates/{templateId}/publish": { "post": { "operationId": "adminPublishTemplate", "tags": [ "admin" ], "summary": "Publish template (Admin); audit event; refused unless a qualification record binds it to an admitted machine", "description": "D-19(b)/(c). Admin session; no step-up required. 409 when no qualification_records row binds the template to at least one admitted machine; fixtures never publish.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "202": { "description": "Publish accepted; audit event recorded." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/machines/{id}/approve": { "post": { "operationId": "adminApproveMachine", "tags": [ "admin" ], "summary": "Approve machine (Admin); reason + expected version; in-flight work gets explicit policy, not silent deletion", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason", "expected_version" ], "properties": { "reason": { "type": "string", "minLength": 1 }, "expected_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Approved." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/machines/{id}/quarantine": { "post": { "operationId": "adminQuarantineMachine", "tags": [ "admin" ], "summary": "Quarantine machine (Admin); reason + expected version; in-flight work gets explicit policy, not silent deletion", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason", "expected_version" ], "properties": { "reason": { "type": "string", "minLength": 1 }, "expected_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Quarantined." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/refunds": { "post": { "operationId": "adminCreateRefund", "tags": [ "admin" ], "summary": "Refund (Admin+recentMFA); evidence/reason, exact immutable manifest or compensating journal; no raw balance-edit endpoint", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "job_id", "amount_micro", "reason", "evidence" ], "properties": { "job_id": { "$ref": "#/components/schemas/UUID" }, "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "reason": { "type": "string", "minLength": 1 }, "evidence": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "202": { "description": "Refund adjustment committed once; cumulative cap enforced." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/payouts/{id}/approve": { "post": { "operationId": "adminApprovePayout", "tags": [ "admin" ], "summary": "Approve payout manifest (Admin+recentMFA); exact immutable manifest hash; destination change invalidates approval", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "manifest_hash", "reason" ], "properties": { "manifest_hash": { "$ref": "#/components/schemas/Sha256Hash" }, "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "202": { "description": "Approved." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/payouts/{id}/signed-transaction": { "post": { "operationId": "adminSubmitSignedTransaction", "tags": [ "admin" ], "summary": "Submit signer-produced raw transaction (Admin+recentMFA); verified to match approved manifest and signer; returns deterministic hash", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "raw_transaction" ], "properties": { "raw_transaction": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" } } } } } }, "responses": { "202": { "description": "Accepted for broadcast.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tx_hash" ], "properties": { "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/payouts/{id}/review": { "post": { "operationId": "adminReviewPayout", "tags": [ "admin" ], "summary": "Approve or reject a host payout held by the automatic payout path (Admin + TOTP step-up). approve releases the hold (the worker re-runs every correctness check); reject fails the unsigned request and releases its locked balance", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 } } } } } }, "responses": { "202": { "description": "Decision recorded (audited with the admin and reason).", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "decision", "state" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "payout", "withdrawal" ] }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "state": { "type": "string", "enum": [ "INTENT", "FAILED" ] } } } } } }, "409": { "description": "The request is no longer unsigned (a nonce is pinned); it cannot be reviewed." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/withdrawals/{id}/review": { "post": { "operationId": "adminReviewWithdrawal", "tags": [ "admin" ], "summary": "Approve or reject a renter withdrawal held by the automatic payout path (Admin + TOTP step-up). approve releases the hold (the worker re-runs every correctness check); reject fails the unsigned request and releases its locked balance", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 2000 } } } } } }, "responses": { "202": { "description": "Decision recorded (audited with the admin and reason).", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "decision", "state" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "kind": { "type": "string", "enum": [ "payout", "withdrawal" ] }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "state": { "type": "string", "enum": [ "INTENT", "FAILED" ] } } } } } }, "409": { "description": "The request is no longer unsigned (a nonce is pinned); it cannot be reviewed." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/admissions": { "post": { "operationId": "adminSetAdmissions", "tags": [ "admin" ], "summary": "Pause/resume admissions (Admin+recentMFA); pauses new jobs/credits as appropriate, never abrupt tenant termination", "description": "While public admission is paused, only a valid acceptance authorization (see schemas/acceptance-authorization.schema.json) consumed by the shared paid_admission_guard permits funding credit, reservation, host publication, payout and withdrawal.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "enabled", "reason" ], "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "202": { "description": "Admission state committed." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/settings": { "get": { "operationId": "adminListSettings", "tags": [ "admin" ], "summary": "List settings (Admin); the D-20 registry grouped by category, plus every root-of-trust key rendered read-only; a secret value is always {set, updated_at}, never the value", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Settings grouped by category.", "content": { "application/json": { "schema": { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "required": [ "category", "settings" ], "properties": { "category": { "type": "string", "enum": [ "branding", "contact", "money", "mail", "alerts", "auth-providers", "chain-access", "operations" ] }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SettingView" } } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/settings/{key}": { "patch": { "operationId": "adminUpdateSetting", "tags": [ "admin" ], "summary": "Update one setting (Admin+recentMFA); typed reason + expected-version CAS; a root-of-trust key is refused 403; a stale version is 409 VERSION_CONFLICT with the current value attached and writes nothing", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "value", "reason", "expected_version" ], "properties": { "value": {}, "reason": { "type": "string", "minLength": 1 }, "expected_version": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Written. The new version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "version" ], "properties": { "key": { "type": "string" }, "version": { "type": "integer" } } } } } }, "409": { "description": "Version conflict — nothing was overwritten.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "current" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "VERSION_CONFLICT" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "request_id": { "type": "string" } } }, "current": { "$ref": "#/components/schemas/SettingView" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/settings/test": { "post": { "operationId": "adminTestSetting", "tags": [ "admin" ], "summary": "Test one subsystem's connectivity (Admin, rate limited); mail/alerts/chain-access/auth-provider; the target always comes from the stored setting, never the request body", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subsystem" ], "properties": { "subsystem": { "type": "string", "enum": [ "mail", "alerts", "chain-access", "auth-provider" ] }, "provider": { "type": "string", "enum": [ "github", "google" ] } } } } } }, "responses": { "200": { "description": "The real result of the check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "detail" ], "properties": { "ok": { "type": "boolean" }, "detail": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/health/live": { "get": { "operationId": "getLiveness", "tags": [ "health" ], "summary": "Liveness (public minimal)", "security": [], "responses": { "200": { "description": "Process alive.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true } } } } } } } } }, "/api/v1/health/ready": { "get": { "operationId": "getReadiness", "tags": [ "health" ], "summary": "Readiness (public minimal); schema/DB/worker/clock with redacted degraded reasons; no internal topology leakage", "security": [], "responses": { "200": { "description": "Ready.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ready" ], "properties": { "ready": { "const": true } } } } } }, "503": { "description": "Degraded; redacted reasons.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ready", "degraded" ], "properties": { "ready": { "const": false }, "degraded": { "type": "array", "items": { "enum": [ "schema", "database", "worker" ] } } } } } } } } } }, "/api/v1/status": { "get": { "operationId": "getStatus", "tags": [ "health" ], "summary": "Public status (minimal)", "description": "While admissions_paused is true, new reservations are refused with 403 ADMISSION_PAUSED; running rentals are unaffected.", "security": [], "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "contract_version", "admissions_paused", "time" ], "properties": { "service": { "const": "AmpleRun" }, "contract_version": { "type": "integer" }, "admissions_paused": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "null when the state could not be read." }, "time": { "$ref": "#/components/schemas/Rfc3339Utc" } } } } } } } } } } }