{ "openapi": "3.0.3", "info": { "title": "PZERO Marketplace API", "description": "Frontier First AI Marketplace. Top up. Do your thing. Repeat. Text, image, and video inference on a two-sided DIEM marketplace. Cleared capacity trades between 30 and 80 cents on the dollar (minimum 20% off $1 DIEM face). Platform fee is 10% of gross USDC on each clear. Inference uses a persistent Bearer API key (pzero_...); account and supply management use a Privy session cookie. Streaming is supported (SSE). Buyer concurrency gate is currently disabled in code (buyerConcurrencyLimitEnabled = false). Human-oriented guide: GET /llms.txt on this API host.", "version": "1.0.0", "contact": { "url": "/" } }, "servers": [ { "url": "/", "description": "Same origin that served this OpenAPI document" } ], "tags": [ { "name": "public", "description": "No authentication" }, { "name": "inference", "description": "Bearer pzero_... API key" }, { "name": "auth", "description": "SIWE sign-in and session lifecycle" }, { "name": "account", "description": "Buyer account (session cookie)" }, { "name": "supply", "description": "Supplier operations (session cookie)" }, { "name": "agent", "description": "Agent self-service (Bearer pzero_... API key, no browser)" } ], "paths": { "/llms.txt": { "get": { "tags": [ "public" ], "summary": "Agent-facing integration guide", "operationId": "getLlmsTxt", "responses": { "200": { "description": "Plain-text integration guide", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "security": [] } }, "/SKILL.md": { "get": { "tags": [ "public" ], "summary": "Agent skill entry point", "description": "Loadable agent skill with YAML frontmatter: what PZERO is, when to reach for it, the handful of facts that prevent the common failures, and links onward to llms.txt, pricing.md, marketplace.md and this spec. Deliberately short — llms.txt carries the detail. Also served at /skill.md; the two paths return the same document.", "operationId": "getAgentSkill", "responses": { "200": { "description": "Markdown document with YAML frontmatter", "content": { "text/markdown": { "schema": { "type": "string" } } } } }, "security": [] } }, "/pricing.md": { "get": { "tags": [ "public" ], "summary": "How a charge is computed", "description": "Explains usage price versus clearing price, what maxPriceCentsPerDollar does, and which refusal maps to which fix. Carries no rate tables: live numbers are on GET /v1/models, GET /v1/capacity, and POST /v1/video/quote.", "operationId": "getPricingMarkdown", "responses": { "200": { "description": "Markdown document", "content": { "text/markdown": { "schema": { "type": "string" } } } } }, "security": [] } }, "/marketplace.md": { "get": { "tags": [ "public" ], "summary": "How supply is priced and matched", "description": "Explains the two-sided market, cheapest-first routing, fall-forward, and the difference between a price constraint and a depth constraint — the distinction behind no_eligible_supply versus insufficient_routable_at_price.", "operationId": "getMarketplaceMarkdown", "responses": { "200": { "description": "Markdown document", "content": { "text/markdown": { "schema": { "type": "string" } } } } }, "security": [] } }, "/openapi.json": { "get": { "tags": [ "public" ], "summary": "This OpenAPI specification", "operationId": "getOpenAPI", "responses": { "200": { "description": "OpenAPI 3.0 document", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/healthz": { "get": { "tags": [ "public" ], "summary": "Liveness probe", "operationId": "getHealthz", "responses": { "200": { "description": "Service is up", "content": { "text/plain": { "schema": { "type": "string", "example": "ok" } } } } }, "security": [] } }, "/v1/models": { "get": { "tags": [ "public" ], "summary": "Public model catalog", "description": "Use a status \"live\" entry's id (Venice model slug) as the model field in text, image, or video inference. Pricing shape depends on modality.", "operationId": "listModels", "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } }, "security": [] } }, "/v1/models/stats": { "get": { "tags": [ "public" ], "summary": "Relative per-model popularity", "description": "Rank and usage share only; raw request counts, token counts, wallets, and request ids are intentionally omitted. When aggregate volume is below the privacy threshold, hasSufficientVolume is false and models is empty.", "operationId": "getModelStats", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "7d" } } ], "responses": { "200": { "description": "Popularity stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelStats" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [] } }, "/v1/market/stats": { "get": { "tags": [ "public" ], "summary": "Live corridor depth, buyer savings, and today's clears", "operationId": "getMarketStats", "responses": { "200": { "description": "Market statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStats" } } } } }, "security": [] } }, "/v1/capacity": { "get": { "tags": [ "public" ], "summary": "What is buyable right now, and at what posted prices", "description": "Pre-flight for agents: GET /v1/models says what is callable, this says what is fundable. Depth comes from the same eligibility predicate the router selects on, so capacity cannot advertise supply the router would refuse. The whole response is cached for 30 seconds, so totals lag posted changes by up to that long. No supplier identity is exposed.", "operationId": "getCapacity", "parameters": [ { "name": "maxPriceCents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 30, "maximum": 80 }, "description": "Narrow the ladder to prices at or below this ask and restate the totals for that slice." } ], "responses": { "200": { "description": "Routable DIEM per posted price plus live modalities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capacity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [] } }, "/v1/supply/pool/summary": { "get": { "tags": [ "public" ], "summary": "Posted-price pool depth (no supplier identity)", "operationId": "getPoolSummary", "responses": { "200": { "description": "Routable DIEM per posted price", "content": { "application/json": { "schema": { "type": "object", "properties": { "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PoolSummaryRow" } } } } } } } }, "security": [] } }, "/auth/privy/verify": { "post": { "tags": [ "auth" ], "summary": "Verify Privy tokens and create session", "description": "Verifies Privy access + identity JWTs. walletAddress must appear in the identity token linked_accounts. Upserts the account (same-wallet SIWE rows upgrade in place) and sets HttpOnly pzero_session.", "operationId": "verifyPrivy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Privy access token (JWT)" }, "walletAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Embedded wallet address bound to the Privy user" }, "identityToken": { "type": "string", "description": "Privy identity JWT with linked_accounts" }, "privyLoginSurface": { "type": "string", "enum": [ "wallet", "embedded", "unknown" ] } }, "required": [ "accessToken", "identityToken", "walletAddress" ] } } } }, "responses": { "200": { "description": "Session created; pzero_session cookie set", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "HttpOnly pzero_session cookie" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionIdentity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [] } }, "/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Revoke the current session", "operationId": "logout", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Session revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/me": { "get": { "tags": [ "account" ], "summary": "Session account identity", "operationId": "getMe", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Signed-in account", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "walletAddress": { "type": "string" }, "authProvider": { "type": "string", "enum": [ "privy", "siwe" ] } }, "required": [ "accountId", "walletAddress", "authProvider" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account": { "get": { "tags": [ "account" ], "summary": "Balances, max price, and recent ledger", "operationId": "getAccount", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Account summary. confirmedUsdc funds inference; pending top-ups do not. hasEverFunded / firstFundedAt distinguish never-funded from spent-to-zero.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/max-price": { "patch": { "tags": [ "account" ], "summary": "Set buyer max clearing price", "operationId": "patchMaxPrice", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxPriceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80 } }, "required": [ "maxPriceCentsPerDollar" ] } } } }, "responses": { "200": { "description": "Updated max price", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "maxPriceCentsPerDollar": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/api-keys": { "post": { "tags": [ "account" ], "summary": "Create a pzero_... API key", "description": "Plaintext key is returned once and never again. Use it as Authorization: Bearer pzero_... on POST /v1/chat/completions.", "operationId": "createApiKey", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Key created; plaintext shown once", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "apiKey": { "type": "string", "description": "Plaintext pzero_... key" } }, "required": [ "name", "apiKey" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/api-keys/{id}": { "delete": { "tags": [ "account" ], "summary": "Revoke an API key", "operationId": "revokeApiKey", "security": [ { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/UuidId" } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account/inference-history": { "get": { "tags": [ "account" ], "summary": "Buyer inference history", "operationId": "getBuyerInferenceHistory", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Paginated buyer inference rows", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/savings": { "get": { "tags": [ "account" ], "summary": "Savings vs face and ceiling", "operationId": "getSavings", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Savings summary", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/x402/top-up": { "post": { "tags": [ "account" ], "summary": "Fund prepaid USDC credits (x402 exact scheme)", "description": "Account funding, not per-request payment. First call without X-PAYMENT returns HTTP 402 with payment requirements. Sign EIP-3009 (scheme exact, Base USDC) and retry with the same body plus the X-PAYMENT header. Payer wallet must match the signed-in session wallet. Top-ups confirm after 20 blocks on Base mainnet; pending balances do not fund inference.", "operationId": "topUp", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded signed x402 payment payload. Omit on the first call to receive requirements." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountMicroUsdc": { "type": "integer", "format": "int64", "minimum": 1000000, "maximum": 1000000000, "description": "Integer micro-USDC (6 decimals on Base). 1000000 = 1.000000 USDC. Not a decimal string — send 1234567 for 1.234567 USDC." } }, "required": [ "amountMicroUsdc" ] } } } }, "responses": { "200": { "description": "Payment settled; credit recorded (pending until confirmed on-chain)", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Payment required: requirements in accepts[], or the submitted payment failed before settlement. A 402 always carries accepts and always means no money moved. Settled money that could not be credited is 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpPaymentRequired" } } } }, "403": { "description": "Payment payer does not match signed-in wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Settled but not completed. The payment moved on chain and the request did not finish; the body carries transaction and reconciling. reconciling: true means the payment is queued and will be credited from the chain; reconciling: false means even that write failed and a human has to recover it. Do not send the payment again.", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettledIncomplete" } } } } } } }, "/v1/x402/signup": { "post": { "tags": [ "account" ], "summary": "Create a funded account and an API key with one payment", "description": "No authentication: the settled payment is the credential. The account wallet is the payer the facilitator verified and the chain confirmed, so no walletAddress request field exists. First call without X-PAYMENT returns HTTP 402 with payment requirements and performs no facilitator call and no writes. Account, credit, and key commit in one transaction. The credit lands pending, so poll GET /v1/agent/me until confirmedUsdc covers the first request. Presenting a settlement that was already credited returns HTTP 200 with idempotent true and no apiKey, so a replay cannot mint a second key. This route cannot attribute callers behind the proxy chain, so it carries a global fuse on outbound facilitator calls rather than a per-IP quota.", "operationId": "x402Signup", "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded signed x402 payment payload. Omit on the first call to receive requirements." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountMicroUsdc": { "type": "integer", "format": "int64", "minimum": 1000000, "maximum": 1000000000, "description": "Integer micro-USDC (6 decimals on Base). 1000000 = 1.000000 USDC. Not a decimal string — send 1234567 for 1.234567 USDC." }, "keyName": { "type": "string", "maxLength": 64, "description": "Name for the minted key. Defaults to x402-signup." }, "maxPriceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80, "description": "Buyer max clearing price for the new account. Omitted defaults to 49, which is below some posted supply: if GET /v1/capacity reports cheapestPostedCents above your ceiling, inference is refused with 503 no_eligible_supply until you raise it via PATCH /v1/agent/max-price." } }, "required": [ "amountMicroUsdc" ] } } } }, "responses": { "200": { "description": "Payment settled. Either the account and key were created, or this settlement was already credited (idempotent true, no apiKey).", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Payment required: requirements in accepts[], or the submitted payment failed before settlement. A 402 always carries accepts and always means no money moved. Settled money that could not be credited is 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpPaymentRequired" } } } }, "409": { "description": "Settled but not completed. The payment moved on chain and the request did not finish; the body carries transaction and reconciling. reconciling: true means the payment is queued and will be credited from the chain; reconciling: false means even that write failed and a human has to recover it. A paid signup on a wallet already holding the maximum active keys answers here too, with credited: true and no key issued. Do not send the payment again.", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettledIncomplete" } } } }, "429": { "description": "Global signup facilitator fuse tripped; retry after the Retry-After interval", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the fuse window resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error before any payment settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/x402/refill": { "post": { "tags": [ "agent" ], "summary": "Fund prepaid USDC with a Bearer key instead of a session", "description": "Bearer twin of POST /v1/x402/top-up: an agent funds its own account without a browser. A session cookie is rejected. The payment payer must be the wallet behind the presented key, checked before settlement. Refill moves balance only; it mints no key. Inference is never paid per request.", "operationId": "x402Refill", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded signed x402 payment payload. Omit on the first call to receive requirements." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountMicroUsdc": { "type": "integer", "format": "int64", "minimum": 1000000, "maximum": 1000000000, "description": "Integer micro-USDC (6 decimals on Base). 1000000 = 1.000000 USDC. Not a decimal string — send 1234567 for 1.234567 USDC." } }, "required": [ "amountMicroUsdc" ] } } } }, "responses": { "200": { "description": "Payment settled; credit recorded (pending until confirmed on-chain)", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Payment required: requirements in accepts[], or the submitted payment failed before settlement. A 402 always carries accepts and always means no money moved. Settled money that could not be credited is 409.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpPaymentRequired" } } } }, "403": { "description": "Payment payer is not the wallet behind the presented API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Settled but not completed. The payment moved on chain and the request did not finish; the body carries transaction and reconciling. reconciling: true means the payment is queued and will be credited from the chain; reconciling: false means even that write failed and a human has to recover it. Do not send the payment again.", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 settlement receipt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettledIncomplete" } } } } } } }, "/v1/agent/me": { "get": { "tags": [ "agent" ], "summary": "Runway for the presented key", "description": "A fresh top-up lands pending and is only spendable once it confirms, so an agent polls this to know when it can spend and how much runway is left. A session cookie is rejected.", "operationId": "getAgentMe", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Wallet, balances, max price, and confirmation depth", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMe" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent/requests/{support_reference}": { "get": { "tags": [ "agent" ], "summary": "Resolve one own request by support reference", "description": "Every inference response carries X-Pzero-Support-Reference. This resolves one the caller's own account owns, and is how the cost of a streamed completion is recovered when the client did not read the pzero.cost SSE frame. Video readiness polls store no attempt row and send no support reference.", "operationId": "getAgentRequest", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "support_reference", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request detail including cost and clearing price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequestDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Support reference not found on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agent/max-price": { "patch": { "tags": [ "agent" ], "summary": "Move the caller's own price ceiling", "description": "The highest cents-per-dollar this account will clear against. Signup can set a ceiling once, but posted prices move, so an agent that only ever gets 503 no_eligible_supply is holding a stale ceiling, not an empty balance: that refusal names cheapestPostedCents, which is the value to send here. Bearer only, like the rest of the agent surface; a request carrying a session cookie is rejected. Any walletAddress in the body is ignored — the account is the one the key authenticates.", "operationId": "patchAgentMaxPrice", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxPriceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80 } }, "required": [ "maxPriceCentsPerDollar" ] } } } }, "responses": { "200": { "description": "Ceiling updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "maxPriceCentsPerDollar": { "type": "integer" } }, "required": [ "walletAddress", "maxPriceCentsPerDollar" ] } } } }, "400": { "description": "Outside the 30–80 corridor, or missing; nothing is changed and nothing is clamped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent/keys": { "post": { "tags": [ "agent" ], "summary": "Mint another key on the caller's own account", "description": "Rotation without a browser: mint, store, verify, then revoke the old key. Each step is separately recoverable, unlike one atomic rotate whose lost response would leave the caller with a revoked key and no replacement. Plaintext is returned once.", "operationId": "createAgentKey", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 64 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Key created; plaintext shown once", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Plaintext pzero_... key" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" } }, "required": [ "apiKey", "name", "keyPrefix" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Active key limit reached; revoke a key before minting another", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "agent" ], "summary": "List active keys on the caller's own account", "description": "Metadata only; plaintext exists once at create. This is how a compromised key's siblings are found before revoking.", "operationId": "listAgentKeys", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Active keys and the cap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent/keys/{id}": { "delete": { "tags": [ "agent" ], "summary": "Revoke one key on the caller's own account", "description": "Includes the calling key, so an agent can retire the credential it is holding.", "operationId": "revokeAgentKey", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "API key not found on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "inference" ], "summary": "OpenAI-compatible chat completion", "description": "OpenAI-compatible chat completion. Streaming is supported: set \"stream\": true for SSE relay; omit or set false for buffered JSON. Fall-forward retries happen before any SSE bytes are written. On retryable upstream or transport failures the router tries up to five distinct supplier keys before surfacing an error. Buyer concurrency gate (HTTP 429 buyer_concurrency_limit) is currently disabled in code. The router clears the cheapest eligible seller offer at or below your maxPriceCentsPerDollar; debits use confirmed USDC only.", "operationId": "createChatCompletion", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "OpenAI-compatible chat completion. A streamed response cannot carry cost headers (the head is written before the relay and there are no trailers), so it emits one extra SSE frame with object pzero.cost after the final usage chunk and before [DONE], carrying costUsdc, clearingPriceCents, and supportReference with an empty choices array.", "headers": { "X-Balance-Remaining": { "schema": { "type": "string" }, "description": "Confirmed USDC balance after settlement, six decimal places" }, "X-Pzero-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Per-request id; present on every inference response including errors" }, "X-Pzero-Support-Reference": { "schema": { "type": "string", "format": "uuid" }, "description": "Resolve at GET /v1/agent/requests/{support_reference}" }, "X-Pzero-Cost-Usdc": { "schema": { "type": "string" }, "description": "What this request cost. Buffered responses only; streams use the pzero.cost SSE frame." }, "X-Pzero-Clearing-Price-Cents": { "schema": { "type": "integer" }, "description": "Posted ask this request cleared at" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "400": { "description": "Malformed request or model not live", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}.", "schema": { "type": "string" } } } }, "401": { "description": "Missing/invalid Bearer, or session cookie sent instead of Bearer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } } } }, "402": { "description": "Confirmed USDC balance insufficient", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } } } }, "404": { "description": "Model not found; use a live model id from GET /v1/models", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } } } }, "429": { "description": "buyer_concurrency_limit: one in-flight completion per wallet when the buyer concurrency gate is enabled (currently disabled in code)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal failure: settle_failed (upstream succeeded but settlement did not commit) or adapter_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } } } }, "502": { "description": "upstream_error or upstream_timeout: upstream HTTP failure or transport failure after fall-forward exhaustion (or immediate non-retryable upstream)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } } } }, "503": { "description": "No eligible supply: no_eligible_supply, insufficient_routable_at_price, pool_empty, or key_wait_timeout (see WriteSupplyFailure). Not returned after partial fall-forward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatError" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } } } } } } }, "/v1/image/generate": { "post": { "tags": [ "inference" ], "summary": "Generate an image", "operationId": "generateImage", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "resolution": { "type": "string" }, "quality": { "type": "string" }, "aspect_ratio": { "type": "string" }, "variants": { "type": "integer", "minimum": 1, "maximum": 4 }, "hide_watermark": { "type": "boolean", "description": "Omitted means the provider's default, which watermarks the image. Set true for an unmarked image; price is unchanged (resolution x quality x variants)." } }, "additionalProperties": true, "description": "Fields PZERO does not price are forwarded to the upstream provider unchanged and keep the provider's defaults (for example hide_watermark, safe_mode, format, seed, steps). enable_web_search is rejected because it bills beyond published pricing." } } } }, "responses": { "200": { "description": "Generated image(s), base64-encoded in images[]. No URL is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" }, "description": "Base64-encoded image data, one entry per variant. WebP unless format was set. Decode client-side; there is no hosted URL." }, "request": { "type": "object", "description": "The upstream request as executed, including defaults applied by the provider." }, "timing": { "type": "object" } } } } } }, "401": { "description": "Missing/invalid Bearer" }, "402": { "description": "Confirmed USDC balance insufficient" }, "429": { "description": "buyer_concurrency_limit" }, "503": { "description": "no_eligible_supply" } } } }, "/v1/images/generations": { "post": { "tags": [ "inference" ], "summary": "Generate an image (OpenAI-compatible path)", "operationId": "generateImageOpenAICompatible", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "OpenAI-compatible image request: model and prompt are required, n replaces variants (1-4). Same passthrough rule as /v1/image/generate, including hide_watermark (default: watermarked)." } } } }, "responses": { "200": { "description": "Venice image JSON response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/video/queue": { "post": { "tags": [ "inference" ], "summary": "Quote, settle, and queue video generation", "operationId": "queueVideo", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "duration": { "type": "string" }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string" }, "audio": { "type": "boolean" }, "image_url": { "type": "string", "description": "Primary still for image-to-video. Aliases image / imageUrl are accepted and canonicalized. For reference-to-video, may be mirrored from reference_image_urls[0] when Venice requires image_url." }, "reference_image_urls": { "type": "array", "items": { "type": "string" }, "description": "Reference stills for reference-to-video. Either this or image_url (or aliases) is required for those models." }, "elements": { "type": "array", "items": { "type": "object" }, "description": "Optional Venice elements payload for models that accept structured scene elements" }, "scene_image_urls": { "type": "array", "items": { "type": "string" }, "description": "Optional scene stills accepted by some Venice video models alongside or instead of image_url" } } } } } }, "responses": { "200": { "description": "Queued video job", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "queue_id": { "type": "string" }, "status": { "type": "string" } } } } }, "headers": { "X-Pzero-Cost-Usdc": { "description": "USDC charged for this request, six decimal places.", "schema": { "type": "string" } }, "X-Pzero-Clearing-Price-Cents": { "description": "Clearing price in cents per $1 DIEM face.", "schema": { "type": "integer" } }, "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } } } }, "401": { "description": "Missing/invalid Bearer", "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } } } }, "402": { "description": "Confirmed USDC balance insufficient", "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } } } }, "429": { "description": "buyer_concurrency_limit", "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "no_eligible_supply / insufficient_routable_at_price / pool_empty / key_wait_timeout", "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } }, "X-Pzero-Support-Reference": { "description": "Reference for GET /v1/agent/requests/{support_reference}. Omitted where no lookupable record was stored (readiness polls, and failures before the key resolved).", "schema": { "type": "string" } }, "X-Pzero-Error-Code": { "description": "Stable machine-readable error code.", "schema": { "type": "string" } } } } } } }, "/v1/video/quote": { "post": { "tags": [ "inference" ], "summary": "Preview video generation cost without settling", "operationId": "quoteVideo", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "duration": { "type": "string" }, "resolution": { "type": "string" }, "aspect_ratio": { "type": "string" }, "audio": { "type": "boolean" }, "image_url": { "type": "string", "description": "Primary still for image-to-video. Aliases image / imageUrl are accepted and canonicalized. For reference-to-video, may be mirrored from reference_image_urls[0] when Venice requires image_url." }, "reference_image_urls": { "type": "array", "items": { "type": "string" }, "description": "Reference stills for reference-to-video. Either this or image_url (or aliases) is required for those models." }, "elements": { "type": "array", "items": { "type": "object" }, "description": "Optional Venice elements payload for models that accept structured scene elements" }, "scene_image_urls": { "type": "array", "items": { "type": "string" }, "description": "Optional scene stills accepted by some Venice video models alongside or instead of image_url" } } } } } }, "responses": { "200": { "description": "Estimated charge at buyer max price. No charge and no job is created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_usd": { "type": "string", "description": "Provider cost of the job in USD." }, "quote_diem": { "type": "string", "description": "Job cost in DIEM. Compare against max_eligible_offer_diem; that comparison sets clears_now." }, "estimated_usdc": { "type": "string", "description": "What you would be charged. Compare against confirmedUsdc from GET /v1/agent/me. Queue can 402 on low balance even when clears_now is true; refill via POST /v1/x402/refill." }, "max_price_cents": { "type": "integer", "description": "Your ceiling. Compare against cheapestPostedCents from GET /v1/capacity." }, "max_eligible_offer_diem": { "type": "string", "description": "Largest single offer at or below your ceiling. clears_now is true when quote_diem fits this value." }, "eligible_routable_diem": { "type": "string", "description": "Total DIEM routable at or below your ceiling. Can look fine while max_eligible_offer_diem is too small for the job." }, "clears_now": { "type": "boolean", "description": "Whether quote_diem fits the largest single eligible offer (max_eligible_offer_diem). False splits two ways: max_eligible_offer_diem (or eligible_routable_diem) below quote_diem means the market is too thin for a job this size (retry later or queue a smaller one); eligible_routable_diem of 0 against non-zero capacity means supply is posted above max_price_cents (raise it via PATCH /v1/agent/max-price). Funding is separate: compare estimated_usdc to confirmedUsdc." } } } } } }, "401": { "description": "Missing/invalid Bearer" }, "402": { "description": "Confirmed USDC balance insufficient (prepaid floor before Venice quote)" }, "400": { "description": "Invalid body / model not available" }, "404": { "description": "model not found" }, "429": { "description": "buyer_concurrency_limit" }, "502": { "description": "Venice quote rejected or upstream failure" }, "503": { "description": "pool_empty / no_eligible_supply / insufficient_routable_at_price / keys_busy" } } } }, "/v1/video/retrieve": { "post": { "tags": [ "inference" ], "summary": "Poll or retrieve video media", "operationId": "retrieveVideo", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "queue_id" ], "properties": { "queue_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Either a JSON status body while the render is in flight, or the MP4 with Content-Type: video/mp4 on delivery. Branch on Content-Type, not the status code. A JSON body reporting status COMPLETED means the provider finished without serving media: stop polling, the job is refunded automatically within 6 hours.", "content": { "application/json": { "schema": { "type": "object" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } } } }, "404": { "description": "Job not found for wallet", "headers": { "X-Pzero-Request-Id": { "description": "Per-request id. Present on every response, including errors, and greppable in server logs.", "schema": { "type": "string" } } } }, "410": { "description": "Job is no longer retrievable: already delivered, refunded, or expired. Save the bytes on first delivery." }, "401": { "description": "Missing/invalid Bearer" } } } }, "/v1/video/complete": { "post": { "tags": [ "inference" ], "summary": "Delete Venice-hosted video media", "operationId": "completeVideo", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "queue_id" ], "properties": { "queue_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Venice completion response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/supply/venice-keys": { "post": { "tags": [ "supply" ], "summary": "Register a supplier Venice API key", "description": "Keys are encrypted at rest (AES-256-GCM). Revoke the upstream Venice key for immediate invalidation.", "operationId": "registerVeniceKey", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "veniceApiKey": { "type": "string" }, "label": { "type": "string" } }, "required": [ "veniceApiKey" ] } } } }, "responses": { "201": { "description": "Key registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeniceKey" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/supply/venice-keys/mine": { "get": { "tags": [ "supply" ], "summary": "List your registered Venice keys", "operationId": "listVeniceKeys", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Registered keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/VeniceKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/supply/venice-keys/{id}": { "delete": { "tags": [ "supply" ], "summary": "Revoke a registered Venice key", "operationId": "revokeVeniceKey", "security": [ { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/UuidId" } ], "responses": { "204": { "description": "Key revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/supply/venice-keys/{id}/sync": { "post": { "tags": [ "supply" ], "summary": "Re-sync a Venice key's DIEM caps from Venice", "operationId": "syncVeniceKey", "security": [ { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/UuidId" } ], "responses": { "200": { "description": "Key with refreshed DIEM figures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeniceKey" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "Could not sync from the Venice API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/supply/offers": { "post": { "tags": [ "supply" ], "summary": "Post a DIEM supply offer", "description": "One active offer per registered Venice key. Platform keeps 10% of gross USDC per clear. DIEM expires at UTC midnight.", "operationId": "postOffer", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80 }, "quantityDiem": { "type": "string", "example": "10.000000", "description": "DIEM face value, decimal string with six places" }, "veniceKeyId": { "type": "string", "format": "uuid" } }, "required": [ "priceCentsPerDollar", "quantityDiem", "veniceKeyId" ] } } } }, "responses": { "201": { "description": "Offer posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An offer already exists for this Venice key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/supply/offers/mine": { "get": { "tags": [ "supply" ], "summary": "List your offers", "operationId": "listOffers", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Your offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/supply/offers/{id}": { "patch": { "tags": [ "supply" ], "summary": "Reprice, pause, or unpause an offer", "description": "Pausing is the soft cancel: status \"paused\" stops routing; \"active\" resumes. There is no DELETE route for offers.", "operationId": "patchOffer", "security": [ { "sessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/UuidId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80 }, "status": { "type": "string", "enum": [ "active", "paused" ] } }, "minProperties": 1 } } } }, "responses": { "200": { "description": "Updated offer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/supply/ledger": { "get": { "tags": [ "supply" ], "summary": "Supplier ledger", "operationId": "getSupplyLedger", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Supplier accruals and payout debits", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/supply/inference-history": { "get": { "tags": [ "supply" ], "summary": "Supplier inference history", "operationId": "getSupplyInferenceHistory", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Paginated supplier-side inference rows", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Persistent pzero_... API key. Inference only; rejected on account and supply routes." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "pzero_session", "description": "HttpOnly session cookie from POST /auth/privy/verify. Rejected on POST /v1/chat/completions." } }, "parameters": { "UuidId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Valid session or credential required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "HTTP status text" }, "message": { "type": "string" } } }, "ChatError": { "type": "object", "description": "Inference error envelope", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "upstream_error" }, "message": { "type": "string" } } } }, "additionalProperties": true }, "StatusOk": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } }, "SessionIdentity": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "accountId": { "type": "string", "format": "uuid" }, "walletAddress": { "type": "string" }, "authProvider": { "type": "string", "enum": [ "privy", "siwe" ] } }, "required": [ "status", "accountId", "walletAddress", "authProvider" ] }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "example": "claude-opus-4-8", "description": "Venice model slug; use as the model field in chat completions" }, "object": { "type": "string", "example": "model" }, "display_name": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "coming_soon" ], "description": "Only live rows are callable and include pricing" }, "modality": { "type": "string", "example": "text" }, "tier": { "type": "string" }, "default_max_output_tokens": { "type": "integer", "nullable": true }, "max_output_tokens": { "type": "integer", "nullable": true }, "context_tokens": { "type": "integer", "nullable": true, "description": "Available context window in tokens from Venice model_spec.availableContextTokens" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "reasoning", "vision", "audio_input", "video_input", "image_generation", "video_generation", "code", "function_calling" ] } }, "is_beta": { "type": "boolean" }, "is_deprecated": { "type": "boolean" }, "supports_vision": { "type": "boolean" }, "supports_reasoning": { "type": "boolean" }, "optimized_for_code": { "type": "boolean" }, "pricing": { "$ref": "#/components/schemas/ModelPricing" }, "first_seen_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "display_name", "status", "modality" ] }, "ModelPricing": { "type": "object", "description": "Micro-USDC per million tokens", "properties": { "input_per_million": { "type": "integer", "format": "int64" }, "output_per_million": { "type": "integer", "format": "int64" }, "cache_per_million": { "type": "integer", "format": "int64" } } }, "ModelStats": { "type": "object", "description": "Relative popularity only. No raw counts.", "properties": { "window": { "type": "string" }, "hasSufficientVolume": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "usageShare": { "type": "number" } }, "additionalProperties": true } } }, "additionalProperties": true }, "MarketStats": { "type": "object", "description": "Live corridor snapshot. DIEM quantities are decimal strings; USDC amounts are decimal strings with six places.", "properties": { "ready": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" }, "corridor": { "type": "object", "properties": { "floorCents": { "type": "integer", "example": 30 }, "capCents": { "type": "integer", "example": 80 }, "bucketStepCents": { "type": "integer", "example": 5 } } }, "availableDepth": { "type": "object", "additionalProperties": true }, "supplyDepth": { "type": "object", "additionalProperties": true }, "demandDepth": { "type": "object", "additionalProperties": true }, "clearedVolumeToday": { "type": "object", "additionalProperties": true }, "clearPriceCents": { "type": "object", "additionalProperties": true }, "buyerSavings": { "type": "object", "properties": { "avgClearingPriceCents": { "type": "number" }, "avgDiscountVsFacePercent": { "type": "number" }, "clearsCount": { "type": "integer" }, "diemCleared": { "type": "string" }, "grossGmvUsdc": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "PoolSummaryRow": { "type": "object", "properties": { "priceCentsPerDollar": { "type": "integer" }, "routableDiem": { "type": "string", "example": "10.000000" } } }, "TopUpSuccess": { "type": "object", "properties": { "balanceUsdc": { "type": "string", "description": "Alias of confirmedUsdc" }, "confirmedUsdc": { "type": "string" }, "pendingUsdc": { "type": "string" }, "topUpAmountUsdc": { "type": "string" }, "walletAddress": { "type": "string" }, "idempotent": { "type": "boolean", "description": "True when this transaction was already credited" }, "confirmationBlocks": { "type": "integer", "description": "Confirmations required before a pending top-up becomes spendable", "example": 20 } } }, "TopUpPaymentRequired": { "type": "object", "properties": { "x402Version": { "type": "integer", "example": 1 }, "amountMicroUsdc": { "type": "integer", "format": "int64", "description": "Integer micro-USDC echoed from the request (1000000 = 1.000000 USDC)." }, "error": { "type": "string", "description": "Present when a submitted payment failed" }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/X402Requirement" } }, "payer": { "type": "string", "description": "Lowercase payer address recovered from the submitted payment. Present when the payment was rejected because the payer does not match the account this route credits." } }, "additionalProperties": true }, "SignupSuccess": { "type": "object", "description": "apiKey is present only when this payment created the account. A replayed settlement returns idempotent true with balances and no key.", "properties": { "apiKey": { "type": "string", "description": "Plaintext pzero_... key, shown once" }, "keyName": { "type": "string" }, "keyPrefix": { "type": "string" }, "walletAddress": { "type": "string", "description": "The verified payer; never a request field" }, "accountId": { "type": "string", "format": "uuid" }, "pendingUsdc": { "type": "string", "description": "The signup credit lands pending, so this is normally the full amount" }, "confirmedUsdc": { "type": "string", "description": "Spendable balance; normally 0.000000 immediately after signup" }, "topUpAmountUsdc": { "type": "string" }, "maxPriceCentsPerDollar": { "type": "integer" }, "transaction": { "type": "string", "description": "Settlement transaction hash" }, "confirmationBlocks": { "type": "integer", "description": "Blocks until the pending credit becomes spendable" }, "idempotent": { "type": "boolean", "description": "True when this settlement was already credited; no key is issued" } } }, "AgentMe": { "type": "object", "properties": { "walletAddress": { "type": "string" }, "accountId": { "type": "string", "format": "uuid" }, "keyPrefix": { "type": "string", "description": "Prefix of the key that made this call" }, "confirmedUsdc": { "type": "string", "description": "Spendable balance; only this funds inference" }, "pendingUsdc": { "type": "string" }, "hasEverFunded": { "type": "boolean", "description": "True once any top-up has been credited (pending or confirmed). Distinguishes never-funded from spent-to-zero." }, "firstFundedAt": { "type": "string", "format": "date-time", "description": "UTC timestamp of the first top-up credit; omitted when hasEverFunded is false" }, "maxPriceCentsPerDollar": { "type": "integer" }, "topUpConfirmationBlocks": { "type": "integer" } } }, "AgentRequestDetail": { "type": "object", "properties": { "supportReference": { "type": "string", "format": "uuid" }, "requestId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "model": { "type": "string" }, "modality": { "type": "string", "enum": [ "text", "image", "video" ] }, "status": { "type": "string" }, "httpStatus": { "type": "integer" }, "errorCode": { "type": "string" }, "errorMessage": { "type": "string" }, "costUsdc": { "type": "string", "description": "What this request cost; empty when nothing settled" }, "clearingPriceCents": { "type": "integer" }, "diemCleared": { "type": "string" }, "totalMs": { "type": "integer" }, "inferenceMs": { "type": "integer" } } }, "AgentKeyList": { "type": "object", "properties": { "activeApiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true } } } }, "activeApiKeyCount": { "type": "integer" }, "maxActiveApiKeys": { "type": "integer" } } }, "Capacity": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "routableDiem": { "type": "string", "description": "Total routable DIEM across the eligible ladder" }, "usdcToBuyAll": { "type": "string", "description": "USDC needed to clear that whole ladder at posted asks" }, "cheapestPostedCents": { "type": "integer", "nullable": true }, "prices": { "type": "array", "description": "Cheapest posted ask first", "items": { "type": "object", "properties": { "priceCentsPerDollar": { "type": "integer" }, "routableDiem": { "type": "string" }, "usdcToBuyAll": { "type": "string" } } } }, "modalities": { "type": "object", "description": "DIEM is model-agnostic, so a modality gates on the catalog being priced for it, not on separate depth.", "additionalProperties": { "type": "object", "properties": { "available": { "type": "boolean" }, "liveModels": { "type": "integer" } } } } } }, "X402Requirement": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "base" }, "maxAmountRequired": { "type": "string", "example": "10000000" }, "resource": { "type": "string", "example": "https://api.example/v1/x402/top-up" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "payTo": { "type": "string", "description": "Deployment settlement address" }, "maxTimeoutSeconds": { "type": "integer" }, "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "USDC on Base mainnet" }, "extra": { "type": "object", "additionalProperties": true } } }, "ChatCompletionRequest": { "type": "object", "description": "OpenAI chat completion request. Additional OpenAI parameters are forwarded to the upstream model.", "properties": { "model": { "type": "string", "example": "claude-opus-4-8", "description": "A status live id from GET /v1/models" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "nullable": true, "description": "String or OpenAI content-part array. May be null on assistant messages that only carry tool_calls." }, "name": { "type": "string" }, "tool_calls": { "type": "array", "description": "Assistant tool/function calls, forwarded to the upstream model.", "items": { "type": "object", "additionalProperties": true } }, "tool_call_id": { "type": "string", "description": "Required on tool-role messages that return a tool result." } }, "required": [ "role" ], "additionalProperties": true } }, "stream": { "type": "boolean", "description": "Set true for SSE streaming; omit or false for buffered JSON" }, "max_tokens": { "type": "integer" } }, "required": [ "model", "messages" ], "additionalProperties": true }, "ChatCompletionResponse": { "type": "object", "description": "OpenAI-compatible chat completion object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "additionalProperties": true }, "finish_reason": { "type": "string" } }, "additionalProperties": true } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "VeniceKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "permission": { "type": "string" }, "limitResetPeriod": { "type": "string" }, "diemEpochCap": { "type": "string" }, "diemRemainingSynced": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "veniceKeyId": { "type": "string", "format": "uuid" }, "priceCentsPerDollar": { "type": "integer", "minimum": 30, "maximum": 80 }, "postedDiemCap": { "type": "string" }, "quantityDiemRemaining": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "exhausted" ] }, "keyPermission": { "type": "string" }, "keyLabel": { "type": "string" }, "keyExpiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SettledIncomplete": { "type": "object", "description": "A payment that settled on chain and could not be turned into balance. Carries no accepts: the money already moved, so there is nothing to pay again. Reconciliation credits whatever the chain confirms.", "properties": { "error": { "type": "string", "description": "What stopped the request after settlement" }, "transaction": { "type": "string", "description": "Settlement transaction hash. Keep this value: it is the handle on the money." }, "reconciling": { "type": "boolean", "description": "True when the payment is queued for reconciliation, which credits whatever the chain confirms with no further action from you. False when even that queue write failed: the money still moved, so do not pay again — keep transaction and quote it to support.", "example": true }, "message": { "type": "string" }, "payer": { "type": "string", "description": "Lowercase payer address recovered from the submitted payment" }, "credited": { "type": "boolean", "description": "Signup only: true when the payment was credited but no API key was issued because the wallet is at the active key limit" }, "maxActiveApiKeys": { "type": "integer", "description": "Signup only: the active key ceiling that refused the mint", "example": 10 } }, "additionalProperties": true } } } }