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: <signature> |
Authorization: Bearer inf_xxxPAYMENT-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
Inference (OpenAI-compatible)
Chat completions (streaming + non-streaming).
Responses API-compatible text endpoint for Codex and Responses clients.
Anthropic Messages API ("Anthropic skin") for Claude Code / the Anthropic SDK.
Legacy completions.
Live model catalog; use the endpoint for current counts.
Image generation; canonical-price × discount (per-token / per-image / per-megapixel).
Async video generation (submit → poll → settle).
Async music generation (submit → poll → settle).
Generated media parameter, lifecycle-status, and Responses compatibility contracts.
Also available:
POST /v1/embeddings- text embeddingsPOST /v1/audio/speech- text-to-speechPOST /v1/audio/transcriptions- speech-to-text (Whisper)POST /v1/decisions- structured decisions: OpenAI's Decisions API (input+ an array ofquestions), or the JEV format (state+ a map ofquestions) - see DecisionsGET /v1/media/artifacts/:jobId/:index- download a finished video/music artifact. Authenticated: send your API key or the job'sX-Job-Token, and follow redirectsGET /v1/providers: the curated provider allowlist, with each provider's host andtrustedflag (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.
Secret masking (beta)
An optional extra layer for prompts that may contain credentials. Send X-SI-Mask-Secrets: on, or set mask_secrets: true on a key or on the account, and API keys, private keys, seed phrases, passwords and tokens in a text request are replaced with placeholders before it is routed; every value is put back in the response, everywhere but the model's reasoning. It is off by default, covers /v1/chat/completions, /v1/completions, /v1/responses, /anthropic/v1/messages and /v1/decisions (with their /min{N} mirrors); embeddings and media are sent as they are, without masking (x-si-secret-masking: not_applied). What is masked, what is put back and what that trusts: Secret masking. The header and the response headers: Routing Controls.
A request that asks for masking fails closed: if masking is running and cannot be applied, it is refused and nothing is sent. While masking is paused on the service (secret_masking_available: false), a request that asks for it is sent without masking instead. The errors use the usual envelope; branch on code.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_secret_masking_header | X-SI-Mask-Secrets is not exactly on (or is repeated) |
| 400 | secret_masking_too_large | more text, or more distinct secrets (2,000), than masking scans |
| 400 | secret_in_schema | a secret in a schema enum, const, pattern, default or examples |
| 400 | secret_in_unmaskable_field | a recognisable secret in a field masking cannot change (an id, a name, model, user, a signature, an object key) |
| 409 | secret_in_signed_reasoning | a secret in signed reasoning from the current tool-use turn |
| 500 | secret_masking_failed | masking could not be applied |
| 500 | secret_egress_blocked | a detected secret was found in a body about to go upstream; it was not sent, and any reserve was released |
| 503 | secret_masking_unavailable | the stored setting the request depends on could not be read, or the service cannot confirm right now whether masking is running (retryable) |
invalid_secret_masking_headerMeaning · X-SI-Mask-Secrets is not exactly on (or is repeated)secret_masking_too_largeMeaning · more text, or more distinct secrets (2,000), than masking scanssecret_in_schemaMeaning · a secret in a schema enum, const, pattern, default or examplessecret_in_unmaskable_fieldMeaning · a recognisable secret in a field masking cannot change (an id, a name, model, user, a signature, an object key)secret_in_signed_reasoningMeaning · a secret in signed reasoning from the current tool-use turnsecret_masking_failedMeaning · masking could not be appliedsecret_egress_blockedMeaning · a detected secret was found in a body about to go upstream; it was not sent, and any reserve was releasedsecret_masking_unavailableMeaning · the stored setting the request depends on could not be read, or the service cannot confirm right now whether masking is running (retryable)Every one of these is raised before funds are reserved, except secret_egress_blocked, which stops an attempt that was already funded and releases the reserve.
Market Data (public, no auth)
All models with best prices.
Single model order book.
Live transaction feed.
Price comparison matrix across all providers - the live JSON is at /v1/prices.
Buyer Management
Seller Management
CORS
All /v1/* inference endpoints include CORS headers for browser-based clients. Preflight OPTIONS requests are handled automatically.