API Reference

Base URL: https://api.surplusintelligence.ai/v1

Authentication

Method	Use Case	Header
API key	Programmatic (Cursor, Aider, scripts)	`Authorization: Bearer inf_xxx`
Session cookie	Web UI	Auto-set after Privy login
x402 payment	Autonomous agents (USDC on Base)	`PAYMENT-SIGNATURE:`
MPP payment	Autonomous agents (Tempo)	`Authorization: Payment`

No auth header → returns HTTP 402 with payment requirements for both x402 and MPP.

Endpoints

Inference (OpenAI-compatible)

POST /v1/chat/completions — chat completions (streaming + non-streaming)
POST /v1/responses — Responses API-compatible text endpoint for Codex and Responses clients
POST /v1/completions — legacy completions
GET /v1/models — live model catalog; use the endpoint for current counts
POST /v1/embeddings — text embeddings
POST /v1/images/generations — image generation; canonical-price × discount (per-token / per-image / per-megapixel)
POST /v1/audio/speech — text-to-speech
POST /v1/audio/transcriptions — speech-to-text (Whisper)
POST /v1/video/generations — async video generation (submit → poll → settle)
POST /v1/music/generations — async music generation (submit → poll → settle)
GET /v1/media/artifacts/:jobId/:index — download media artifact (proxy fallback)

Minimum-discount routing

Insert an optional min{N} segment (e.g. /min30/v1/chat/completions) to require marketplace seller offers to meet a minimum estimated buyer discount (min0–min100, no leading zeros) before routing. No qualifying seller returns 503 minimum_discount_not_met. The threshold applies to SI marketplace seller offers only — buyer-owned priority/fallback providers are not covered. Embeddings and MPP/dual-402 min-discount are out of scope in v1. See Minimum-Discount Routing.

Tool calling and Anthropic sellers: Buyers always send OpenAI-format requests. For OpenAI-compatible sellers such as Venice, Bankr, OpenRouter, Together, Fireworks, Groq, Mistral, and DeepSeek, tool support depends on the upstream model and is advertised in GET /v1/models via supported_parameters. For native Anthropic sellers (api.anthropic.com), the router has OpenAI ⇄ Anthropic translation for text, vision, streaming, tool calls, assistant tool_calls, and role: "tool" result messages. That translation is implemented and covered by tests, but there are currently no active native Anthropic seller offers in production; Claude traffic is primarily served through OpenAI-compatible providers. Non-function computer/text-editor style tools are stripped, and models that do not advertise tool support have tools/tool_choice removed before forwarding.

Market Data (public, no auth)

GET /api/markets — all models with best prices
GET /api/markets/:model — single model order book
GET /api/markets/feed — live transaction feed
GET /v1/prices — price comparison matrix across all providers (live JSON)

Buyer Management

Buyer endpoints — keys, balance, savings, usage export, providers

Seller Management

Seller endpoints — offers, discovery, earnings, health log

CORS

All /v1/* inference endpoints include CORS headers for browser-based clients. Preflight OPTIONS requests are handled automatically.