Quickstart.

From a fresh account to your first answer in five minutes. Create a key, send a request, read the envelope, fetch the timeline.

§ 01Sign up & sign in

Head to essarion.com and create an account. After verifying your email you'll land in the dashboard at app.essarion.com. The free plan includes enough credit to walk this whole quickstart end-to-end.

§ 02Create a key

From the dashboard, open Settings → API keys and click Create key. Give it a name that tells you where it's used — local-dev, prod-backend, staging-cron. The plaintext key — beginning with esk_ — is shown exactly once. Copy it now.

§ 03Save it as ESSARION_KEY

Put the key in your environment, not your code. The examples below all read it from $ESSARION_KEY.

export ESSARION_KEY="esk_live_a1b2c3d4..."

For real deployments, use your platform's secrets manager — Vercel env vars, AWS Secrets Manager, Doppler, 1Password Secrets Automation. Don't commit keys, and don't ship them to the client.

§ 04Run your first query

The simplest call is a synchronous POST to /api/v1/query. The endpoint waits for the engine to finish, then returns the full envelope.

curl https://api.essarion.com/api/v1/query \
  -H "Authorization: Bearer $ESSARION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the half-life of caffeine in adults?"}'

const res = await fetch("https://api.essarion.com/api/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ESSARION_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What is the half-life of caffeine in adults?",
  }),
});

const data = await res.json();
console.log(data.answer);
console.log(`request_id: ${data.request_id}`);

import os, httpx

resp = httpx.post(
    "https://api.essarion.com/api/v1/query",
    headers={"Authorization": f"Bearer {os.environ['ESSARION_KEY']}"},
    json={"query": "What is the half-life of caffeine in adults?"},
    timeout=200.0,
)

data = resp.json()
print(data["answer"])
print("request_id:", data["request_id"])

§ 05Read the response envelope

Every response is the same shape. answer is the synthesized text, sources is the citation list, usage is the token and latency accounting, request_id is your handle for fetching the timeline.

{
  "request_id": "req_01HXYZABC123",
  "status": "ok",
  "answer": "The half-life of caffeine in healthy adults is approximately 5 hours...",
  "sources": [
    {
      "title": "Caffeine pharmacokinetics",
      "url": "https://...",
      "domain": "ncbi.nlm.nih.gov",
      "snippet": "...",
      "relevance": 0.94
    }
  ],
  "usage": { "tokens_in": 412, "tokens_out": 1880, "latency_ms": 14320 },
  "errors": [],
  "upstream": { "model": "essarion-research-1", "retries": 0 }
}

Read status first. On ok, use answer and sources. On error, the errors array tells you what went wrong; the HTTP status code tells you which class of error it is. See Errors for the full reference.

§ 06Fetch the timeline

Every run is persisted. The request_id from the response is the handle for retrieving the full step-by-step record — what sub-queries were issued, which sources were discovered, scraped, and analyzed, and what the engine reasoned along the way.

curl https://api.essarion.com/api/v1/runs/req_01HXYZABC123 \
  -H "Authorization: Bearer $ESSARION_KEY"

You'll get back a timeline object with steps, reasoning chunks, and ranked sources. See Run timelines for the full schema.

§ 07Try streaming

For longer queries, the streaming endpoint emits progressive events as the run unfolds. Same auth, same body shape — just a different path and an SSE response.

curl --no-buffer https://api.essarion.com/api/v1/query/stream \
  -H "Authorization: Bearer $ESSARION_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query": "Compare lithium-ion and solid-state batteries for grid storage."}'

Each line prefixed with data: is a JSON event. See Streaming for the full event vocabulary.

§ 08Where to go next

• Queries — full reference for the synchronous endpoint.
• Streaming — every SSE event type, with examples in three languages.
• Run timelines — fetching the persistent record of any query.
• Errors — codes, classes, and retry guidance.
• Your first query, guided — the same path with more commentary.