API reference
The Topo API is a superset of the OpenAI API: same paths, same request and response shapes, plus one topo object for routing, verification and settlement.
Base URL
Every endpoint lives under one base URL. Requests are served from the nearest healthy region automatically.
https://api.topolabs.ai/v1Endpoints
- POST/v1/chat/completionsCreate a chat completion
- POST/v1/embeddingsEmbed text for search and retrieval
- POST/v1/images/generationsGenerate images from a prompt
- GET/v1/modelsList models and live prices
- GET/v1/walletRead your balance and deposit addresses
- GET/v1/receipts/{id}Fetch a signed inference receipt
- POST/v1/agentsCreate an agent wallet
Headers
Send JSON bodies. Every response carries an x-topo-request-id header: quote it when you write to support.
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer followed by your API key. |
Content-Type | On POST | Always application/json. |
Topo-Version | No | Pin a dated API version such as 2026-10-01. Defaults to the version your key was created on. |
Idempotency-Key | No | Any unique string. Retries with the same key are served and billed once. |
The topo object
Topo extensions live under one topo field so they never collide with OpenAI parameters. SDKs that reject unknown fields can send it through extra_body.
topo.regionstringKeep the request in one region, such as
eu-west-2. Max and Enterprise plans.topo.prioritystringpriorityskips the standard queue at peak. Builder plans and up.Default:
standardtopo.verificationstringstrictchecks every response with three attestors before release. See Verification.Default:
sampledtopo.max_coststring (USDT)Reject the request with
402if its estimated cost is higher than this.topo.fallbackstring[]Model IDs to try, in order, when the requested model has no healthy capacity.
Versioning
Breaking changes ship as a new dated version. Older versions stay supported for at least 12 months after a successor ships, and every deprecation is announced in the changelog and by email.