Endpoints

All operation routes below are relative to:

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

Create routes return 202 Accepted with an operation id. Poll the matching GET route until the operation reaches a terminal status.

Route overview

API-key authentication supports all four operations. x402 currently supports Search only.

Search

Use Standard Search for a direct cited answer. Use explicit Agent mode for longer multi-step web, social, and crypto research.

Search request fields

The stable text-search flow only needs query and, when needed, an explicit search_mode. URL mode is retained for compatibility; Agent mode combined with URL input is rejected before work or billing starts.

curl --fail-with-body https://api-onchain.optimai.network/external/v1/search \
  -H "X-API-Key: $OPTIMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: endpoint-search-001" \
  -d '{
    "query": "Analyze the latest OptimAI ecosystem and crypto market news",
    "search_mode": "agent"
  }'

search_mode defaults to "search". Agent mode accepts text queries only; Agent mode combined with URL input returns 400 invalid_request before work or billing starts.

A completed response contains:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "query": "Analyze the latest OptimAI ecosystem and crypto market news",
  "result": {
    "answer": "...",
    "citations": [
      {
        "id": 1,
        "url": "https://example.com/article",
        "title": "Example source",
        "snippet": "..."
      }
    ]
  }
}

Search also supports GET /search/:id/events for Server-Sent Events and DELETE /search/:id for cancellation.

The events endpoint streams text/event-stream updates while a Search is in progress. Event names include search.started, search.progress, search.completed, search.warning, search.failed, and search.done. Each event carries JSON data such as stage, message, percent, and partial source or answer fields. If the Search is already terminal, the events endpoint returns 409; use GET /search/:id for the final response.

List searches

API-key clients can list their recent Search operations with:

GET /search?limit=20&offset=0&status=completed

Optional filters are limit (1–100, default 20), offset (0 or greater), status, created_after, and created_before (ISO 8601 timestamps). The response contains data items with id, status, query, timestamps, and credits_charged, plus pagination with total, limit, offset, and has_more. This list route is part of API-key access; the x402 Search path is operation-ID based.

Scrape

Use Scrape for one known public URL.

POST /scrape

{ "url": "https://example.com/article" }

Scrape supports GET /scrape/:id and DELETE /scrape/:id.

Seed

Use Seed to discover URLs from a starting URL without recursively extracting every page.

POST /seed

{
  "seed_url": "https://example.com/docs",
  "max_urls": 100,
  "include_subdomains": false
}

max_urls must be between 1 and 1000. Poll GET /seed/:id for the result. Use DELETE /seed/:id to cancel a pending or running operation when allowed.

Crawl

Use Crawl to traverse and extract pages from a site within explicit limits.

POST /crawl

{
  "seed_url": "https://example.com/docs",
  "max_pages": 50,
  "max_depth": 2,
  "include_external": false,
  "allow_subdomains": false
}

max_pages must be between 1 and 100; max_depth must be between 0 and 5. Poll GET /crawl/:id for the result. Use the matching DELETE route to cancel a pending or running operation when cancellation is still allowed.

Idempotency

Send a unique Idempotency-Key header with create requests.

• The same key and request returns 303 See Other with a Location header.
• A changed body, route, or Search mode with the same key returns 409 Conflict.
• Omitted search_mode and explicit "search" are equivalent.
• A new operation needs a new idempotency key.