DocsAPIOverview

Platform API.

A programmatic surface for the same engine that powers the products. Submit queries, stream events, fetch run timelines, manage keys.

§ 01What the API is

The Platform API is a thin Next.js gateway that sits in front of the Essarion research engine. The same engine that runs behind the workspace and the research UI is callable here, with the same identity model and the same persistent run records.

The gateway handles authentication, plan enforcement, request shaping, response envelopes, and event streaming. The engine behind it does the actual planning, retrieval, scraping, scoring, and synthesis. From the outside, you see one HTTP surface — small, predictable, and stable.

NoteIf you're new, start with Quickstart. It walks from key creation through a working request in under five minutes.

§ 02What you can do with it

The API is deliberately small. There are five things to do, and the rest of these docs is detail on how to do each one well.

Run a query. POST a question, get a citation-grade answer back synchronously. See Queries.
Stream a query. Same input shape, but events are emitted as the run unfolds — discovery, scraping, analysis, reasoning, final. See Streaming.
Fetch a run timeline. Every query has a request_id. Use it to retrieve the full step-by-step record after the fact. See Run timelines.
Manage keys. Create, list, and revoke API keys from the dashboard or programmatically through the session-protected key endpoints. See API keys.
Inspect usage. Aggregated analytics — calls, tokens, latency, daily breakdown, recent runs. See Usage.

§ 03Base URL

All requests go to a single host.

BASEhttps://api.essarion.com

Every endpoint path documented in this section is rooted at that host. Examples in these docs use the absolute URL throughout so you can copy and run them without ceremony.

§ 04Versioning

The public surface lives under /api/v1/. The version is part of the path, not a header. That keeps caches honest and makes log lines easy to triage.

POST/api/v1/query

Endpoints under /api/keys and /api/usage are dashboard-side and intentionally unversioned — they are the management plane, not the data plane.

§ 05Content types

Requests are application/json. Responses are either application/json for synchronous endpoints or text/event-stream for streamed ones. Always send and accept UTF-8.

curl

curl https://api.essarion.com/api/v1/query \
  -H "Authorization: Bearer $ESSARION_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"query": "..."}'

§ 06Compatibility & deprecation

We never break v1 endpoints in place. Breaking changes ship as /api/v2/ alongside the existing surface. Additive changes — new optional fields, new event types, new response keys — can land in v1 without notice. Plan your client to ignore unknown fields.

When v2 ships, v1 stays available for at least twelve months, with deprecation banners in the dashboard and a clearly dated retirement notice. Sunset dates are communicated by email to every account that has called the affected endpoint in the prior thirty days.

§ 07Rate limits

Rate limits are enforced per plan and surfaced in the response envelope when they trip. A request that exceeds the limit gets a 429 with an errors array describing the bucket and the retry guidance. See Errors for the full envelope.

The dashboard shows your current plan ceilings under Settings → Plan. There are three buckets — requests per minute, concurrent streams, and tokens per day — each with its own threshold.

TipTreat 429 as a signal to back off, not to fail. Exponential backoff with jitter starting at 500ms and capping at 16s handles every realistic burst the API will return.

§ 08Response envelope

Every successful response from the data-plane endpoints carries the same shape. The keys are stable across versions; values are typed but tolerant of new fields.

Field	Type	Description
request_id	string	Unique identifier for this run. Use it to fetch the timeline at `/api/v1/runs/{request_id}`.
status	string	One of `ok` or `error`. On `error` the `errors` array is populated.
answer	string	The synthesized answer text. Empty on error or for streamed endpoints before the final event.
sources	array	Sources used in the answer. Each has `title`, `url`, `domain`, `snippet`, and citation metadata.
usage	object	Token and latency accounting — `tokens_in`, `tokens_out`, `latency_ms`.
errors	array	Zero or more `{ code, message }` objects. Empty on success.
upstream	object	Diagnostic metadata from the engine — model routing, retry counts, partial failures. Safe to ignore in production code.

An error response uses the same envelope, with status: "error" and a populated errors array. The HTTP status code reflects the class of error; the body explains the specifics. See Errors for the full reference.