{ "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" }, "servers": [ { "url": "/" } ], "tags": [ { "name": "catalog" }, { "name": "jobs" }, { "name": "account" }, { "name": "wallets" }, { "name": "billing" }, { "name": "hosts" }, { "name": "support" }, { "name": "admin" }, { "name": "health" } ], "components": { "securitySchemes": { "sessionAuth": { "type": "http", "scheme": "bearer", "description": "Pinned Better Auth session credential. Step-up (recent re-auth / MFA) 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}$" }, "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$" }, "DecimalString": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Unsigned base-10 integer as string; never a float." }, "MicroAmount": { "$ref": "#/components/schemas/DecimalString" }, "EvmAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "Sha256Hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "ImageDigest": { "type": "string", "pattern": "^[^@\\s]+@sha256:[0-9a-f]{64}$" }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "retryable", "request_id" ], "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "retryable": { "type": "boolean" }, "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" } ] } } }, "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" }, "ram_bytes": { "$ref": "#/components/schemas/DecimalString" }, "disk_bytes": { "$ref": "#/components/schemas/DecimalString" }, "measured_bandwidth_mbps": { "$ref": "#/components/schemas/DecimalString" }, "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." } }, "description": "No host management address is ever exposed." }, "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." }, "estimated_total_micro": { "$ref": "#/components/schemas/MicroAmount", "description": "D-19(c): floor(total_rate_micro_per_hour * duration_limit_s / 3600), fee included; informational \u2014 the quote's budget_micro remains the only price authority." } } }, "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" } } }, "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" } } }, "BalanceSet": { "type": "object", "additionalProperties": false, "required": [ "spendable_micro", "held_micro", "pending_micro", "disputed_micro", "withdrawable_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" } } }, "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" } ] } } }, "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>) \u2014 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" } } }, "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" } } } }, "responses": { "Error": { "description": "Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 503 unavailable money/provider state with retryable:true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "paths": { "/api/v1/offers": { "get": { "tags": [ "catalog" ], "summary": "List admitted offers (public)", "description": "Filter by model, minimum VRAM, GPU count, total machine price, region, RAM/disk, measured bandwidth and template compatibility. Only available, recently healthy admitted offers can reserve. No cached public responses. With template_id (D-19(c)) every item carries a server-computed fit object.", "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)). Unknown or unpublished template -> 404." }, { "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." } ], "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": { "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": { "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." } ], "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": { "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": { "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.", "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 or image_digest (422 otherwise). With template_id the server resolves the published template's pinned image_digest and requires the offer to fit (422).", "properties": { "offer_id": { "$ref": "#/components/schemas/UUID" }, "image_digest": { "$ref": "#/components/schemas/ImageDigest", "description": "Custom OCI image; required unless template_id is given." }, "duration_limit_s": { "type": "integer", "minimum": 1 }, "budget_micro": { "$ref": "#/components/schemas/MicroAmount" }, "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." } } } } } }, "responses": { "201": { "description": "Immutable quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs": { "post": { "tags": [ "jobs" ], "summary": "Reserve job from quote (quote owner)", "description": "Atomically holds budget, reserves machine, increments fence and queues start. Rejects expired quote, changed manifest, unavailable machine or insufficient spendable funds without partial holds.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quote_id", "ssh_public_key" ], "properties": { "quote_id": { "$ref": "#/components/schemas/UUID" }, "ssh_public_key": { "type": "string", "minLength": 1 } } } } } }, "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": { "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": { "tags": [ "jobs" ], "summary": "Job status, cumulative charge, funded-through (owner/admin)", "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": { "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": { "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", "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" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/jobs/{id}/stop": { "post": { "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 } } } } } }, "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": { "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 \u2014 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": { "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": { "tags": [ "account" ], "summary": "Profile/security metadata (self); no password/token hashes", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Account profile." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/sessions": { "get": { "tags": [ "account" ], "summary": "Session metadata (self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Active sessions." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/sessions/{id}": { "delete": { "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": { "tags": [ "account" ], "summary": "List API keys (self)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "API key metadata; secrets never re-shown." }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "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." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/account/api-keys/{id}": { "delete": { "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/export": { "post": { "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": { "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": { "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": { "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": { "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": { "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/wallets/{binding_id}/payout-destination": { "post": { "tags": [ "wallets" ], "summary": "Select proved, versioned payout destination (verified self, recent re-auth/SIWE)", "description": "Future transfer intents bind wallet_binding_id,address,version; pending intents never retarget.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "binding_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Destination version selected." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/funding-intents": { "post": { "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}/claim": { "post": { "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. 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": { "tags": [ "billing" ], "summary": "Balance summary (self/admin); spendable/held/pending/disputed/withdrawable separately", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Balances.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSet" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/billing/entries": { "get": { "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": { "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." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/withdrawals": { "post": { "tags": [ "billing" ], "summary": "Create withdrawal (self, step-up)", "description": "Locked withdrawal intent; raw/unproved destination rejected; no spendable credit while transfer pending.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_micro", "wallet_binding_id", "destination_version" ], "properties": { "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "wallet_binding_id": { "$ref": "#/components/schemas/UUID" }, "destination_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Withdrawal intent locked." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/enrollment-tokens": { "post": { "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/hosts/machines": { "get": { "tags": [ "hosts" ], "summary": "List own machines (host owner/admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Page of machine summaries." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}": { "get": { "tags": [ "hosts" ], "summary": "Machine detail: compatibility findings, current offer/job, observed metrics, drain state (host owner/admin)", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } ], "responses": { "200": { "description": "Machine detail." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/machines/{id}/offer": { "post": { "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" } } } }, "/api/v1/hosts/machines/{id}/list": { "post": { "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": { "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": { "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/earnings": { "get": { "tags": [ "hosts" ], "summary": "Earnings (host owner): earned, disputed, payable, requested, settled; gross vs 10% fee; no utilization guess", "security": [ { "sessionAuth": [] } ], "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" ], "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" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/hosts/payouts": { "post": { "tags": [ "hosts" ], "summary": "Request payout (host owner, step-up)", "description": "Payout intent locked against payable; raw/unproved destination rejected.", "security": [ { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount_micro", "wallet_binding_id", "destination_version" ], "properties": { "amount_micro": { "$ref": "#/components/schemas/MicroAmount" }, "wallet_binding_id": { "$ref": "#/components/schemas/UUID" }, "destination_version": { "$ref": "#/components/schemas/DecimalString" } } } } } }, "responses": { "202": { "description": "Payout intent locked." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tickets": { "get": { "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": { "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": { "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." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tickets/{id}/messages": { "post": { "tags": [ "support" ], "summary": "Append message (participant/admin)", "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": { "tags": [ "admin" ], "summary": "Admin user view (Admin+MFA); immutable references", "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": { "get": { "tags": [ "admin" ], "summary": "Admin machine view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin job view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin ledger view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin payout view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin ticket view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin audit view (Admin+MFA)", "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": { "tags": [ "admin" ], "summary": "Admin reconciliation view (Admin+MFA); 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": { "tags": [ "admin" ], "summary": "Admin analytics (Admin+MFA); committed capacity, paid time, GMV, fees, costs, refunds and repeat users separated; unavailable inputs stay null", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Analytics." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/admin/templates/{templateId}/publish": { "post": { "tags": [ "admin" ], "summary": "Publish template (Admin+MFA); audit event; refused unless a qualification record binds it to an admitted machine", "description": "D-19(b)/(c). Requires MFA step-up. 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": { "tags": [ "admin" ], "summary": "Approve machine (Admin+MFA); 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": { "tags": [ "admin" ], "summary": "Quarantine machine (Admin+MFA); 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": { "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": { "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": { "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/admissions": { "post": { "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/health/live": { "get": { "tags": [ "health" ], "summary": "Liveness (public minimal)", "security": [], "responses": { "200": { "description": "Process alive." } } } }, "/api/v1/health/ready": { "get": { "tags": [ "health" ], "summary": "Readiness (public minimal); schema/DB/worker/clock with redacted degraded reasons; no internal topology leakage", "security": [], "responses": { "200": { "description": "Ready." }, "503": { "description": "Degraded; redacted reasons." } } } }, "/api/v1/status": { "get": { "tags": [ "health" ], "summary": "Public status (minimal)", "security": [], "responses": { "200": { "description": "Status." } } } } } }