{ "openapi": "3.0.3", "info": { "title": "gaisha API", "version": "0.3.0", "description": "gaisha: OpenAI-compatible inference marketplace with fixed retail pricing, provider offers, ledger, payouts and YooKassa/Stripe top-ups." }, "servers": [ { "url": "http://127.0.0.1:8000", "description": "Local broker" } ], "tags": [ { "name": "auth" }, { "name": "buyer" }, { "name": "chat" }, { "name": "seller" }, { "name": "admin" }, { "name": "payments" } ], "components": { "securitySchemes": { "buyerKey": { "type": "http", "scheme": "bearer" }, "providerToken": { "type": "http", "scheme": "bearer" }, "adminToken": { "type": "apiKey", "in": "header", "name": "X-Admin-Token" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "market_session" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } }, "ChatRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string", "example": "qwen2.5-0.5b" }, "messages": { "type": "array", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "type": "string" } } } }, "stream": { "type": "boolean", "default": false }, "max_tokens": { "type": "integer", "default": 256 }, "temperature": { "type": "number", "default": 0.7 }, "max_price": { "type": "number", "description": "USD per 1M input tokens ceiling" }, "max_cost_usd": { "type": "number", "description": "Hard total budget for the request" } } }, "ChatResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "price_snapshot_id": { "type": "string" }, "provider_id": { "type": "string" } } } } }, "paths": { "/health": { "get": { "tags": [ "admin" ], "summary": "Liveness probe", "responses": { "200": { "description": "OK" } } } }, "/v1/auth/session": { "post": { "tags": [ "auth" ], "summary": "Create browser session from buyer key, provider token or admin token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Session created; Set-Cookie returned" }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "Current session", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Role and subject" }, "401": { "description": "Not authenticated" } } } }, "/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Revoke current session", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Logged out" } } } }, "/v1/buyer/register": { "post": { "tags": [ "buyer" ], "summary": "Register a buyer and receive an API key once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "Buyer created" }, "409": { "description": "Email already exists" } } } }, "/v1/buyer/topup": { "post": { "tags": [ "payments" ], "summary": "Mock Stripe top-up", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_usd" ], "properties": { "amount_usd": { "type": "number", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Balance updated" }, "422": { "description": "Below minimum" } } } }, "/v1/buyer/balance": { "get": { "tags": [ "buyer" ], "summary": "Available and reserved balance", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Balance" } } } }, "/v1/buyer/usage": { "get": { "tags": [ "buyer" ], "summary": "Recent usage records", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Usage list" } } } }, "/v1/buyer/invoice": { "get": { "tags": [ "buyer" ], "summary": "Current invoice summary", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Invoice" } } } }, "/v1/models": { "get": { "tags": [ "chat" ], "summary": "Public model catalog and retail prices", "responses": { "200": { "description": "Model list" } } } }, "/v1/chat/completions": { "post": { "tags": [ "chat" ], "summary": "OpenAI-compatible chat completion (stream or non-stream)", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest", "properties": { "service_class": { "type": "string", "enum": [ "on_demand", "interruptible" ] }, "require_verified": { "type": "boolean", "default": false }, "privacy_tier": { "type": "string", "default": "standard" } } } } } }, "responses": { "200": { "description": "Completion or SSE stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "402": { "description": "Insufficient balance" }, "422": { "description": "Price ceiling or max cost violation" }, "503": { "description": "No capacity" } } } }, "/v1/seller/register": { "post": { "tags": [ "seller" ], "summary": "Register a provider and receive a provider token once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "legal_entity": { "type": "string" } } } } } }, "responses": { "201": { "description": "Provider created" }, "409": { "description": "Already exists" } } } }, "/v1/seller/offers": { "post": { "tags": [ "seller" ], "summary": "Create or update a provider offer", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "base_url", "w_input_usd_per_1m", "w_cached_usd_per_1m", "w_output_usd_per_1m" ], "properties": { "model": { "type": "string" }, "base_url": { "type": "string" }, "region": { "type": "string", "default": "local" }, "max_concurrency": { "type": "integer", "default": 4 }, "w_input_usd_per_1m": { "type": "number" }, "w_cached_usd_per_1m": { "type": "number" }, "w_output_usd_per_1m": { "type": "number" }, "service_class": { "type": "string", "enum": [ "on_demand", "interruptible" ], "default": "on_demand" }, "valid_until": { "type": "string", "format": "date-time", "nullable": true }, "gpu_model": { "type": "string", "nullable": true }, "gpu_count": { "type": "integer", "default": 1 }, "vram_gb": { "type": "integer", "nullable": true }, "tee": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Offer saved" }, "422": { "description": "Outside wholesale corridor" } } }, "get": { "tags": [ "seller" ], "summary": "List provider offers", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Offer list" } } } }, "/v1/seller/earnings": { "get": { "tags": [ "seller" ], "summary": "Provider payable, holdback and lifetime usage", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Earnings" } } } }, "/v1/seller/payouts/request": { "post": { "tags": [ "seller" ], "summary": "Request a payout", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_usd": { "type": "number" } } } } } }, "responses": { "201": { "description": "Payout pending" }, "422": { "description": "Invalid amount" } } } }, "/v1/admin/stats": { "get": { "tags": [ "admin" ], "summary": "GMV, margin, counts and platform balances", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Stats" } } } }, "/v1/admin/providers": { "get": { "tags": [ "admin" ], "summary": "List providers", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Providers" } } } }, "/v1/admin/providers/{provider_id}/approve": { "post": { "tags": [ "admin" ], "summary": "Approve a provider", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approved" } } } }, "/v1/admin/health": { "get": { "tags": [ "admin" ], "summary": "Provider health", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Health list" } } } }, "/v1/admin/healthcheck": { "post": { "tags": [ "admin" ], "summary": "Run healthcheck immediately", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Results" } } } }, "/v1/admin/ledger": { "get": { "tags": [ "admin" ], "summary": "Recent ledger entries", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Ledger" } } } }, "/v1/admin/payouts": { "get": { "tags": [ "admin" ], "summary": "List payouts", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Payouts" } } } }, "/v1/admin/payouts/{payout_id}/approve": { "post": { "tags": [ "admin" ], "summary": "Approve a payout", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid" } } } }, "/v1/admin/reputation": { "get": { "tags": [ "admin" ], "summary": "Provider reputation and latency", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Reputation list" } } } }, "/v1/admin/requests": { "get": { "tags": [ "admin" ], "summary": "Recent requests", "security": [ { "adminToken": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Requests" } } } }, "/v1/seller/auctions": { "get": { "tags": [ "seller" ], "summary": "Auctions won or served by this provider", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Auction events" } } } }, "/v1/seller/offers/{offer_id}/bid": { "post": { "tags": [ "seller" ], "summary": "Update an offer bid and capacity", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "w_input_usd_per_1m": { "type": "number" }, "w_cached_usd_per_1m": { "type": "number" }, "w_output_usd_per_1m": { "type": "number" }, "max_concurrency": { "type": "integer" }, "context_limit": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated offer" }, "404": { "description": "Offer not found" }, "422": { "description": "Invalid bid" } } } }, "/v1/seller/offers/{offer_id}/status": { "post": { "tags": [ "seller" ], "summary": "Pause or resume an offer", "security": [ { "providerToken": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } } } } } }, "responses": { "200": { "description": "Updated offer" }, "404": { "description": "Offer not found" } } } }, "/v1/admin/auctions": { "get": { "tags": [ "admin" ], "summary": "All auction events and bids", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Auction events" } } } }, "/v1/buyer/keys/{key_id}/budget": { "post": { "tags": [ "buyer" ], "summary": "Set a monthly budget for an API key", "security": [ { "buyerKey": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly_budget_usd": { "type": "number", "nullable": true } } } } } }, "responses": { "200": { "description": "Budget updated" }, "404": { "description": "Key not found" } } } }, "/v1/admin/offers/{offer_id}/verify": { "post": { "tags": [ "admin" ], "summary": "Mark an offer model as verified", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "offer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "default": true }, "method": { "type": "string", "default": "manual" } } } } } }, "responses": { "200": { "description": "Updated offer" }, "404": { "description": "Offer not found" } } } }, "/v1/admin/providers/{provider_id}/verify-identity": { "post": { "tags": [ "admin" ], "summary": "Attach verified domain/GitHub identity", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "nullable": true }, "github": { "type": "string", "nullable": true }, "method": { "type": "string", "default": "manual" } } } } } }, "responses": { "200": { "description": "Provider identity updated" }, "404": { "description": "Provider not found" } } } } } }