{ "openapi": "3.1.0", "info": { "title": "Computalot API", "version": "v1", "summary": "On-demand compute: typed jobs in, structured results out, metered by the second.", "description": "The public Computalot API. All product endpoints live under `/api/v1`.\n\nAgent-first docs: `/skill.md` (agent skill), `/llms.txt` (compact), `/llms-full.txt` (full), `/api/v1/docs` (JSON index). Human docs: `/docs`. Pricing: `/docs/pricing`.\n\nError envelope: failures return `{error, recommended_action?, details?}` — `recommended_action` tells the caller what to do next. Additive changes (new fields/endpoints) ship without notice; write clients that tolerate unknown fields. Breaking changes are announced at `/docs/changelog`.", "contact": { "name": "Computalot feedback (no auth)", "url": "https://computalot.com/api/v1/feedback" } }, "servers": [ { "url": "https://computalot.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "discovery", "description": "Docs and machine-readable references. No auth." }, { "name": "ops", "description": "Health and operator metrics." }, { "name": "auth", "description": "Wallet auth, registration policy, waitlist." }, { "name": "account", "description": "Balance, ledger, holds, quotes, x402 funding." }, { "name": "projects", "description": "Your code: create, push, init, status, shared KV." }, { "name": "jobs", "description": "Typed job submission, inspection, streaming, cancel." }, { "name": "results", "description": "Terminal results and aggregates." }, { "name": "artifacts", "description": "File inputs/outputs with account-scoped IDs." }, { "name": "feedback", "description": "Bug reports and feature requests. No auth." } ], "paths": { "/": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Landing page (HTML) with waitlist form.", "responses": { "200": { "description": "HTML landing page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/skill.md": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Agent skill file — the agent onboarding entrypoint.", "responses": { "200": { "description": "Markdown skill file with frontmatter triggers.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Compact LLM/agent API reference.", "responses": { "200": { "description": "Compact markdown reference.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/llms-full.txt": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Full LLM/agent reference with tutorials.", "responses": { "200": { "description": "Full markdown reference.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/docs": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Human documentation site.", "responses": { "200": { "description": "HTML docs site.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "This OpenAPI 3.1 document.", "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/docs": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Machine-readable JSON docs index (auth, billing, endpoints, quickstart, debugging).", "responses": { "200": { "description": "JSON documentation index.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/docs/python-sdk": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Python SDK guide (markdown).", "responses": { "200": { "description": "Python SDK guide.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/api/v1/docs/workflows": { "get": { "tags": [ "discovery" ], "security": [ {} ], "summary": "Workflow patterns guide (markdown).", "responses": { "200": { "description": "Workflow patterns guide.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/health": { "get": { "tags": [ "ops" ], "security": [ {} ], "summary": "Liveness probe.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/live": { "get": { "tags": [ "ops" ], "security": [ {} ], "summary": "Liveness probe.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/ready": { "get": { "tags": [ "ops" ], "security": [ {} ], "summary": "Readiness probe (503 until the controller core is up).", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/metrics": { "get": { "tags": [ "ops" ], "summary": "Prometheus metrics (operator-gated: metrics token, admin auth, or local request).", "responses": { "200": { "description": "Prometheus text exposition.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing/invalid operator credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/register": { "post": { "tags": [ "auth" ], "security": [ {} ], "summary": "Self-service API-key issuance — permanently answers 403 with current access guidance.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } } } } } }, "responses": { "403": { "description": "Access guidance: wallet auth (details.wallet_auth), waitlist (details.waitlist), or admin-issued keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/wallet/challenge": { "post": { "tags": [ "auth" ], "security": [ {} ], "summary": "Start wallet auth: create a single-use signing challenge (5 min TTL). Rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet_address" ], "properties": { "wallet_address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain": { "type": "string", "enum": [ "base", "ethereum", "evm" ], "default": "base" } } } } } }, "responses": { "201": { "description": "Challenge created: {challenge: {id, message, expires_at, ...}} — sign `message` (EIP-191 personal_sign).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Wallet not allowed under the current access policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid chain or wallet address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — respect retry-after.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/wallet/verify": { "post": { "tags": [ "auth" ], "security": [ {} ], "summary": "Complete wallet auth: exchange the signed challenge for a 24h session token (fls_...).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "wallet_address", "signature" ], "properties": { "challenge_id": { "type": "string" }, "wallet_address": { "type": "string" }, "signature": { "type": "string" } } } } } }, "responses": { "201": { "description": "Session created: {token: 'fls_...', wallet, account}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Invalid signature or wallet mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wallet not allowed under the current access policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Challenge already used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Challenge expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/waitlist": { "post": { "tags": [ "auth" ], "security": [ {} ], "summary": "Join the waitlist (email). Rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "Joined.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/balance": { "get": { "tags": [ "account" ], "summary": "Canonical balance snapshot.", "responses": { "200": { "description": "Account + balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "additionalProperties": true }, "balance": { "$ref": "#/components/schemas/Balance" } } } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/ledger": { "get": { "tags": [ "account" ], "summary": "Settled credit-ledger entries (paged).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." }, { "name": "entry_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by entry type (e.g. x402_topup, job_charge, beta_credit_grant)." } ], "responses": { "200": { "description": "Paged entries.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/holds": { "get": { "tags": [ "account" ], "summary": "Balance holds (paged).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "released", "captured", "partially_captured", "expired" ] } } ], "responses": { "200": { "description": "Paged holds.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/quotes": { "get": { "tags": [ "account" ], "summary": "Funding and shortfall quotes (paged).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "paid", "expired", "cancelled", "consumed" ] } }, { "name": "quote_type", "in": "query", "schema": { "type": "string", "enum": [ "x402_topup", "job_shortfall", "generic" ] } } ], "responses": { "200": { "description": "Paged quotes.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/quotes/{quote_id}": { "get": { "tags": [ "account" ], "summary": "One quote by id (account-scoped), including its x402 payment requirements.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "External quote id (qt_...)." } ], "responses": { "200": { "description": "Account + quote.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "additionalProperties": true }, "quote": { "$ref": "#/components/schemas/Quote" } } } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id or another account's quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/quotes/topup": { "post": { "tags": [ "account" ], "summary": "Create an x402 top-up quote. Always answers 402 with signable payment requirements.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_usd" ], "properties": { "amount_usd": { "type": "number", "minimum": 0.01, "maximum": 10000 }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "402": { "description": "Fresh quote advertising both payment protocols: x402 payment_required (also base64-encoded in the `payment-required` response header) and an MPP challenge (mpp.dev) in the `WWW-Authenticate: Payment` response header, with a decoded copy in the body's `mpp` block. Re-POSTing this path with an MPP `Authorization: Payment ` settles the quote the credential references instead of creating a new one (201/200 with a `Payment-Receipt` response header).", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/Quote" }, "payment_required": { "$ref": "#/components/schemas/PaymentRequired" }, "mpp": { "type": "object", "additionalProperties": true, "description": "MPP (mpp.dev) challenge summary: protocol, method (evm), intent (charge), and the decoded challenge request (amount in base units, currency contract address, recipient, chainId). Mirrors the WWW-Authenticate: Payment header." } } } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Malformed amount or above the per-top-up cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "x402 not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/quotes/{quote_id}/pay/x402": { "post": { "tags": [ "account" ], "summary": "Settle a quote via x402 or MPP and credit the account. Idempotent on replay.", "description": "Two credential carriers settle the same quote. x402: send the base64-encoded payment payload in the `PAYMENT-SIGNATURE` header (bearer auth required). MPP (mpp.dev): send `Authorization: Payment ` carrying an EIP-3009 authorization — no bearer token needed (the credential plus the unguessable single-use quote id authorize the settlement); success adds a base64url JSON `Payment-Receipt` response header. Without any credential, the response is 402 re-quoting the payment requirements over both protocols (PAYMENT-REQUIRED + WWW-Authenticate: Payment).", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 carrier: base64(JSON x402 payment payload) — no prefix, no quotes." }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Bearer token for the x402 carrier, or `Payment ` for the MPP carrier ({challenge, payload: {type: \"authorization\", from, to, value, validAfter, validBefore, nonce, signature}, source})." } ], "responses": { "201": { "description": "Settled: {account, quote, payment, balance, replay: false}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "200": { "description": "Replay of an already-settled quote: {…, replay: true}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Missing credential (re-quote over both protocols) or facilitator declined (payment_response included).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Quote not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid PAYMENT-SIGNATURE payload, malformed MPP credential, unsupported MPP credential type (only `authorization` is accepted), or MPP challenge id not matching the URL quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Facilitator not configured or unavailable — retry with backoff, preserving the same credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects": { "post": { "tags": [ "projects" ], "summary": "Create a project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "remote_dir" ], "properties": { "name": { "type": "string" }, "remote_dir": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "201": { "description": "Project created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Name or remote_dir already taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "projects" ], "summary": "List projects for the caller's account.", "responses": { "200": { "description": "{projects: [...]}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}": { "get": { "tags": [ "projects" ], "summary": "Project detail and init status.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Project detail.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "projects" ], "summary": "Update project metadata (code updates go through /push).", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "projects" ], "summary": "Delete a project (refused while jobs are active).", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Active jobs still reference the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/push": { "post": { "tags": [ "projects" ], "summary": "Upload project code as a raw gzipped tarball (Dockerfile + computalot.project.json + code).", "description": "Body is the raw `.tar.gz` bytes (not multipart, not JSON). The revision publishes immediately on success; runtime preparation happens on demand.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "requestBody": { "required": true, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Revision published (may include tarball_diff).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Project busy initializing/refreshing — retry after it settles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid tarball or manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/init": { "post": { "tags": [ "projects" ], "summary": "Optional pre-warm: prepare currently available workers for the active revision.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Init started/refreshed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Available balance below the $5.00 funding floor — shortfall quote attached; fund and retry the same request.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/invalidate": { "post": { "tags": [ "projects" ], "summary": "Invalidate the cached project revision.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Invalidated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/cancel-queued": { "put": { "tags": [ "projects" ], "summary": "Cancel all queued/planning jobs for this project.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Cancelled count.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/status": { "get": { "tags": [ "projects" ], "summary": "Public readiness: published vs ready_for_jobs.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Readiness snapshot.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/status/details": { "get": { "tags": [ "projects" ], "summary": "Detailed readiness breakdown (replica counts, sanitized diagnostics).", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Detailed readiness.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/stream": { "get": { "tags": [ "projects" ], "summary": "SSE stream of this project's job updates.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Server-sent events.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/kv": { "get": { "tags": [ "projects" ], "summary": "List shared-KV entries.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." } ], "responses": { "200": { "description": "Entries.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{name}/kv/{key}": { "get": { "tags": [ "projects" ], "summary": "Get a shared-KV value.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{key, value}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project or key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "projects" ], "summary": "Put a shared-KV value.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Stored.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "projects" ], "summary": "Delete a shared-KV value.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project name." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project or key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs": { "post": { "tags": [ "jobs" ], "summary": "Submit a typed job.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSubmit" } } } }, "responses": { "201": { "description": "Job with summary.billing_estimate (authoritative quote) and billing_hold when funded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits — shortfall quote + payment_required attached; fund the account, then retry the same request.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid contract (dependencies, retries, fan-out, resources, reserved fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "jobs" ], "summary": "List jobs (account-scoped; heavy fields stripped).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "project", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{jobs, total, count, limit, offset}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/batch": { "post": { "tags": [ "jobs" ], "summary": "Submit up to 200 jobs atomically.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/JobSubmit" }, "maxItems": 200 } }, "additionalProperties": true } } } }, "responses": { "201": { "description": "Created jobs.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits for the batch.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Any invalid job rejects the batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/watch": { "get": { "tags": [ "jobs" ], "summary": "SSE multiplex-watch of up to 100 job ids.", "parameters": [ { "name": "ids", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated job ids (max 100)." } ], "responses": { "200": { "description": "Job update frames; terminal frames preserve meta/variant and persistence flags.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Too many or malformed ids.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}": { "get": { "tags": [ "jobs" ], "summary": "Job detail (request, summary with billing fields, error/output presence).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "Job detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/tasks": { "get": { "tags": [ "jobs" ], "summary": "The job's tasks (per-task status, output, exit_code, progress, checkpoint).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "{tasks: [...]}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/events": { "get": { "tags": [ "jobs" ], "summary": "Lifecycle event log (30-day retention).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." } ], "responses": { "200": { "description": "{events: [...]}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/metrics": { "get": { "tags": [ "jobs" ], "summary": "Aggregate runtime metrics (task counts, retries, throughput).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "Metrics rollup.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/output": { "get": { "tags": [ "jobs" ], "summary": "Convenience output/error view.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "Output view.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/stream": { "get": { "tags": [ "jobs" ], "summary": "SSE stream of one job's updates.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "responses": { "200": { "description": "Server-sent events.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/jobs/{id}/cancel": { "put": { "tags": [ "jobs" ], "summary": "Cancel a job (settles billing to actual use).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job id." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/results": { "get": { "tags": [ "results" ], "summary": "Search terminal results (30-day window).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." }, { "name": "project", "in": "query", "schema": { "type": "string" } }, { "name": "client_ref", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated job ids." } ], "responses": { "200": { "description": "Result summaries.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/results/{job_id}": { "get": { "tags": [ "results" ], "summary": "Aggregated result for one job: summary, aggregate_result, per-task results, completeness, artifact ids.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated result envelope.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts": { "post": { "tags": [ "artifacts" ], "summary": "Upload artifact bytes through the controller relay (up to 2 GiB).", "description": "Body is the raw bytes (application/octet-stream). Metadata via query/headers per the JSON docs index. Content is deduplicated per account against the 100 GiB retained quota.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Artifact metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactMeta" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "507": { "description": "artifact_quota_exceeded — the response includes authoritative quota limit, used, and remaining bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "artifacts" ], "summary": "List your artifacts (account-scoped).", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Page size." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Page offset." } ], "responses": { "200": { "description": "Account-scoped artifacts plus authoritative quota limit, used, and remaining bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactMeta" } }, "total": { "type": "integer" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "quota": { "$ref": "#/components/schemas/ArtifactQuota" } }, "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/external": { "post": { "tags": [ "artifacts" ], "summary": "Register an external URL artifact (any size).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "sha256": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "201": { "description": "Artifact metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactMeta" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/{id}": { "get": { "tags": [ "artifacts" ], "summary": "Download artifact content (relay/redirect).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Artifact id." } ], "responses": { "200": { "description": "Artifact bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "artifacts" ], "summary": "Delete an artifact once all referencing jobs are terminal.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Artifact id." } ], "responses": { "200": { "description": "Deletion scheduled.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "artifact_in_use — a non-terminal job still references the artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/{id}/meta": { "get": { "tags": [ "artifacts" ], "summary": "Artifact metadata.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Artifact id." } ], "responses": { "200": { "description": "Metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactMeta" } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/direct": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/direct/complete": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/multipart": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/multipart/part": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/multipart/parts": { "get": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/multipart/complete": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/artifacts/multipart/abort": { "post": { "tags": [ "artifacts" ], "deprecated": true, "summary": "Retired presigned upload endpoint — always 410 Gone with migration guidance.", "responses": { "410": { "description": "Retired: use POST /api/v1/artifacts (relay, up to 2 GiB) or POST /api/v1/artifacts/external.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/presets": { "get": { "tags": [ "jobs" ], "summary": "List resource presets (names, shapes, billing classes).", "responses": { "200": { "description": "{presets: [...]}.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Auth required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/feedback": { "post": { "tags": [ "feedback" ], "security": [ {} ], "summary": "Submit feedback — bugs, feature requests, ideas. No auth. Rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmit" } } } }, "responses": { "201": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid type/title.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`flk_...`, issued via the waitlist/admin) or a wallet session token (`fls_...`, 24h, from the wallet challenge/verify flow). Both resolve to the same account surfaces." } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope. `recommended_action` states the next step for the caller.", "required": [ "error" ], "properties": { "error": { "type": "string" }, "recommended_action": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "Balance": { "type": "object", "description": "Account credit snapshot (USD).", "properties": { "account_id": { "type": "integer" }, "ledger_balance_usd": { "type": "number" }, "credited_usd": { "type": "number" }, "debited_usd": { "type": "number" }, "held_usd": { "type": "number" }, "available_usd": { "type": "number" }, "active_hold_count": { "type": "integer" }, "open_quote_count": { "type": "integer" } }, "additionalProperties": true }, "Quote": { "type": "object", "description": "Payment quote. `attrs.x402_payment_required` carries the signable x402 requirements.", "properties": { "id": { "type": "string", "description": "External quote id (qt_...)." }, "account_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "open", "paid", "expired", "cancelled", "consumed" ] }, "quote_type": { "type": "string", "enum": [ "x402_topup", "job_shortfall", "generic" ] }, "amount_usd": { "type": "number" }, "shortfall_amount_usd": { "type": "number" }, "request_hash": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "attrs": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "PaymentRequired": { "type": "object", "description": "x402 payment requirements (x402Version 2). Sign `accepts[0]` with an x402-capable wallet/SDK and send the base64 payload in the PAYMENT-SIGNATURE header.", "properties": { "x402Version": { "type": "integer" }, "quoteId": { "type": "string" }, "resource": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "format": "date-time" }, "accepts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "Job": { "type": "object", "description": "Job object. `summary` carries billing_estimate/billing_hold and, after terminal state, billing_settlement. Public responses never expose infrastructure identities.", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "planning", "running", "completed", "partial", "failed", "cancelled", "lost" ] }, "type": { "type": "string" }, "project": { "type": "string" }, "summary": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "JobSubmit": { "type": "object", "description": "Typed job submission. See `/api/v1/docs` (jobs group) for the full per-field contract and per-type examples.", "required": [ "type", "project" ], "properties": { "type": { "type": "string", "enum": [ "structured_runner", "sweep", "map_reduce", "benchmark" ] }, "runner_command": { "type": "array", "items": { "type": "string" }, "description": "Required." }, "payload": { "type": "object", "additionalProperties": true, "description": "Task input, written to $COMPUTALOT_TASK_PAYLOAD." }, "project": { "type": "string" }, "timeout_s": { "type": "integer", "default": 3600, "description": "Per-task runtime cap after a worker starts the task. Queue time is not charged." }, "gpu_required": { "type": "boolean", "default": false }, "requirements": { "type": "object", "description": "Minimum per-task resources.", "properties": { "cpu": { "type": "integer" }, "memory_mb": { "type": "integer" }, "storage_gb": { "type": "integer" }, "gpu_count": { "type": "integer" }, "gpu_memory_mb": { "type": "integer" }, "profile": { "type": "string" } }, "additionalProperties": false }, "preset": { "type": "string", "description": "Resource preset name from GET /api/v1/presets; explicit requirements override preset values." }, "reservation": { "type": "object", "description": "Only {mode: best_effort} is accepted; other shapes return 422.", "additionalProperties": true }, "checkpointing": { "type": "object", "description": "structured_runner only: {enabled, resume_from_latest, payload_key}.", "additionalProperties": true }, "reliability_mode": { "type": "string", "enum": [ "best_effort", "strict_complete" ] }, "runtime_hint_s": { "type": "integer", "description": "Expected runtime hint for hold estimation." }, "max_retries": { "type": "integer", "minimum": 0, "maximum": 10, "default": 0 }, "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "default": "normal" }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "client_ref": { "type": "string", "maxLength": 255, "description": "Client-supplied grouping/search label." }, "depends_on": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "DAG dependencies (account-accessible job ids)." }, "fan_out": { "type": "object", "description": "structured_runner only: {by}, {items}, or {chunks, total} (mutually exclusive). Optional batch_size/batch_per_task.", "additionalProperties": true }, "merge_strategy": { "type": "string", "enum": [ "collect", "keyed", "weighted_avg" ] }, "parameters": { "type": "object", "description": "sweep only: map of param -> [values]; cartesian product, max 1000 combos.", "additionalProperties": true }, "fixed_payload": { "type": "object", "description": "sweep only: merged into every task.", "additionalProperties": true }, "rank_by": { "type": "string", "description": "sweep/benchmark: result field to rank by (required for sweep)." }, "rank_order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "split": { "type": "object", "description": "map_reduce only: {field, start, total, chunks} or {field, ranges}.", "additionalProperties": true }, "reduce": { "type": "object", "description": "map_reduce only: field -> operator (sum, mean, max, min, weighted_avg:, concat, count, collect).", "additionalProperties": true }, "candidates": { "type": "object", "description": "benchmark only: name -> config (min 2).", "additionalProperties": true }, "shared_payload": { "type": "object", "description": "benchmark only: merged into every task.", "additionalProperties": true }, "replicas": { "type": "integer", "default": 1, "description": "benchmark only: runs per candidate." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ArtifactMeta": { "type": "object", "description": "Artifact metadata. Retained bytes count against the 100 GiB per-account quota.", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "reference_count": { "type": "integer", "description": "All retained job references, active plus terminal." }, "active_reference_count": { "type": "integer", "description": "Non-terminal job references that currently block deletion." }, "terminal_reference_count": { "type": "integer", "description": "Terminal job references; informational and do not block owner deletion." }, "deletion_eligible": { "type": "boolean", "description": "True when no non-terminal job references the artifact." } }, "additionalProperties": true }, "ArtifactQuota": { "type": "object", "description": "Authoritative account retained-artifact quota. Deleted metadata is excluded immediately even while physical GC is pending.", "required": [ "limit_bytes", "used_bytes", "remaining_bytes" ], "properties": { "limit_bytes": { "type": "integer" }, "used_bytes": { "type": "integer" }, "remaining_bytes": { "type": "integer" } }, "additionalProperties": false }, "FeedbackSubmit": { "type": "object", "required": [ "type", "title" ], "properties": { "type": { "type": "string", "enum": [ "bug", "feature_request", "provisioning", "job_type_request" ] }, "title": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true } }, "parameters": {} } }