First Query

Send a natural language query and handle cited live-web output.

Start with one specific question. Search creation is asynchronous: the first request returns an ID, then your client polls that ID for the final result.

const response = await fetch("https://api-onchain.optimai.network/external/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OPTIMAI_API_KEY ?? "",
    "Content-Type": "application/json",
    "Idempotency-Key": "first-query-001",
  },
  body: JSON.stringify({
    query: "What changed in AI agent retrieval this week?",
  }),
})

if (!response.ok) {
  const message = await response.text()
  throw new Error(`OptimAI Search failed: ${response.status} ${message}`)
}

const created = await response.json()

let search = created
while (search.status !== "completed") {
  if (["failed", "cancelled"].includes(search.status)) {
    throw new Error(`Search ended with status ${search.status}`)
  }

  await new Promise((resolve) => setTimeout(resolve, 2_000))
  const poll = await fetch(
    `https://api-onchain.optimai.network/external/v1/search/${created.id}`,
    { headers: { "X-API-Key": process.env.OPTIMAI_API_KEY ?? "" } },
  )
  if (!poll.ok) throw new Error(`Search polling failed: ${poll.status}`)
  search = await poll.json()
}

Minimal response renderer

console.log(search.result?.answer ?? "No answer returned")

for (const source of search.result?.citations ?? []) {
  console.log(`- ${source.title ?? source.url}: ${source.url}`)
}

What to inspect

  • id: the stable ID used for polling and support.
  • status: lifecycle state such as pending, processing, or completed.
  • result.answer: the cited live-web response when completed.
  • result.citations: URLs used to support the answer.

Agent/Crypto mode

Standard Search is the default and costs 1 credit. Send search_mode: "agent" for longer multi-step web, social, and crypto research; it costs 2 credits and only accepts text queries. Use a new idempotency key when changing modes.

UI behavior

Show sources close to the answer. The product promise is trust, so the evidence should not be hidden behind a secondary screen.

Keep the original query and the source list together in logs. When a user asks "why did the answer say that?", the source URLs are the fastest path to debug the result.