API Overview

Base URLs, request style, and response expectations for decentralized live web search.

The API is designed for decentralized live web retrieval. Keep your client wrapper small: one base URL, one auth header, and explicit handling for non-2xx responses.

Base URL

https://api-onchain.optimai.network/external/v1

Request format

Use JSON request bodies and API key authentication.

X-API-Key: $OPTIMAI_API_KEY
Content-Type: application/json

Search request

POST /search

{
  "query": "What changed in AI search infrastructure this week?",
  "search_mode": "search"
}

The create route returns 202 Accepted with an ID. Poll GET /search/:id, or use GET /search/:id/events for Search events. Standard Search is the default and costs 1 credit. Explicit Agent mode ("search_mode": "agent") costs 2 credits and accepts text queries only.

Response shape

Responses should be machine-readable and easy to render in a product UI.

Field	Meaning
`id`	Stable operation ID used for polling.
`status`	Async lifecycle state.
`result.answer`	Cited Search answer after completion.
`result.citations`	Source URLs and labels for a completed Search.
`result`	Operation-specific output for Scrape, Seed, and Crawl.

See Response Format for lifecycle statuses and a complete Search example. Review Security before putting keys or wallet-backed payment flows into production.

Production handling

Treat 4xx responses as request or credential issues.
Treat 429 and 5xx responses as retryable only with bounded backoff.
Log the operation id for support and retries.
Keep API keys server-side; browser clients should call your backend.