Skip to main content
Surplus Intelligence
Marketplace
API referenceOverview

API Reference

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

Authentication

API keyUse Case · Programmatic (Cursor, Aider, scripts)Header · Authorization: Bearer inf_xxx
Session cookieUse Case · Web UIHeader · Auto-set after Privy login
x402 paymentUse Case · Autonomous agents (USDC on Base)Header · PAYMENT-SIGNATURE: <signature>

No auth header → returns HTTP 402 with x402 payment requirements.

The dashboard is a pure client of this API. Everything you can do in the web app, you can do here: managing keys, providers, offers, pricing, balances, savings, earnings, and payouts are all HTTP calls, no browser required. Most of it works with your API key (inf_… for buyers, si_seller_… for sellers); a few organization, treasury, and admin surfaces are session or management-key gated. See the buyer and seller reference pages below.

  • API key — inf_… or si_seller_…
  • Session cookie — the web app
  • x402 — the payment IS the credential
  • X-Job-Token — one media job only
One router, one order bookthe rail you arrived on does not change routing
No credentialreturns 402 with payment requirements, not 401
Send no credential at all and you get a 402 describing how to pay. Send one that no rail accepts and you get a 401 — the difference matters when you are debugging.

Inference (OpenAI-compatible)

POST /v1/chat/completions

Chat completions (streaming + non-streaming).

Read more →POST /v1/responses

Responses API-compatible text endpoint for Codex and Responses clients.

Read more →POST /anthropic/v1/messages

Anthropic Messages API ("Anthropic skin") for Claude Code / the Anthropic SDK.

Read more →POST /v1/completions

Legacy completions.

Read more →GET /v1/models

Live model catalog; use the endpoint for current counts.

Read more →POST /v1/images/generations

Image generation; canonical-price × discount (per-token / per-image / per-megapixel).

Read more →POST /v1/video/generations

Async video generation (submit → poll → settle).

Read more →POST /v1/music/generations

Async music generation (submit → poll → settle).

Read more →Adapter policy contracts

Generated media parameter, lifecycle-status, and Responses compatibility contracts.

Read more →

Also available:

  • POST /v1/embeddings — text embeddings
  • POST /v1/audio/speech — text-to-speech
  • POST /v1/audio/transcriptions — speech-to-text (Whisper)
  • POST /v1/decisions — structured decisions: OpenAI's Decisions API (input + an array of questions), or the JEV format (state + a map of questions) — see Decisions
  • GET /v1/media/artifacts/:jobId/:index — download a finished video/music artifact. Authenticated: send your API key or the job's X-Job-Token, and follow redirects
  • GET /v1/providers: the curated provider allowlist, with each provider's host and trusted flag (live JSON)

Capability Lookups

Three capabilities vary by model and must be looked up rather than assumed.

  • Media input (images, video, documents, audio sent to a model): Media Inputs. A separate surface from image/video generation.
  • Reasoning effort, including request shapes and marketplace adaptations: Reasoning Controls.
  • Provider identity and what is verified about it: Provider & Model Verification.

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 404 minimum_discount_not_met. The threshold applies to SI marketplace seller offers only — buyer-owned priority/fallback providers are not covered. Embeddings 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.

Read more →GET /api/markets/:model

Single model order book.

Read more →GET /api/markets/feed

Live transaction feed.

Read more →GET /v1/prices

Price comparison matrix across all providers — the live JSON is at /v1/prices.

Read more →

Buyer Management

Buyer endpoints

Keys + per-key routing preferences, balance, savings, usage export, BYOK providers.

Read more →

Seller Management

Seller endpoints

Keys, offers (full lifecycle), discovery + health probes, earnings, payouts.

Read more →

CORS

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