DocsResearchAPI reference

API reference.

The public-facing endpoints for ResearchAnything specifically — start runs, poll, stream, fetch results, manage sources, export citations, and operate projects. For the broader Platform API gateway, see the API overview.

§ 01Authentication

Every endpoint on this page requires authentication. Two methods are supported.

Session cookie (Bearer) — when you're calling from the workspace, the session cookie carries a Bearer token automatically. Most server-side integrations don't use this path.
API key — issue a key from your account settings. API keys carry the esk_ prefix. Pass them in the Authorization header.

curl

curl https://api.essarion.com/api/v1/research/start \
  -H "Authorization: Bearer esk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "What were the headline findings of the IEA 2024 storage report?"}'

NoteThere is also a Platform API gateway at POST /api/v1/query that fronts the entire engine (research plus agents). For its documentation, see API overview. The endpoints below are the ResearchAnything-specific surface.

§ 02Research runs

Start a research run

POST/api/v1/research/start

Starts a new research run. Auth required. Subject to the per-plan daily run limit; if the limit is exceeded, the endpoint returns a quota error.

Param	Type	Required	Description
query	string	required	The research question. Treat this like a brief, not a search box.
maxResultsPerQuery	integer	optional	Cap on the number of search results per sub-query. Tune to widen or narrow discovery.
scrapeConcurrency	integer	optional	Number of parallel scrape workers. Default is tuned for speed without overload.
minWordCount	integer	optional	Minimum words a scraped page must contain to survive screening.
recencyWeight	number	optional	Weight applied to the recency component when computing the composite score.
excludeDomains	string[]	optional	Additional domains to exclude beyond the system defaults.

Poll run status

GET/api/v1/research/{session_id}

Returns the current status of a run, including the active phase, progress, and any error state.

Param	Type	Required	Description
session_id	string	required	Path parameter. The session ID returned from `/research/start`.

Fetch the final result

GET/api/v1/research/{session_id}/result

Returns the final report — executive summary, full report, sources with scores, and citations. Available once the run reaches the complete phase.

Param	Type	Required	Description
session_id	string	required	Path parameter. The session ID for the run.
format	string	optional	Citation format to embed in the response. One of `mla`, `apa`, `chicago-notes`, `chicago-author-date`, `ieee`, `harvard`, `bibtex`.

Event history

GET/api/v1/research/{session_id}/events

Returns the full event history for a run. Useful for replaying the timeline of a completed run, or for catching up after a disconnect.

Live event subscription

WS/api/v1/research/{session_id}/ws

WebSocket endpoint that streams live events as the run progresses — phase transitions, reasoning chunks, partial outputs. Reconnect with the /events endpoint to backfill any gap.

Re-synthesize

POST/api/v1/research/{session_id}/retry

Re-runs the synthesis phase against the existing source set. Useful when you want a different format, length, or angle without paying the cost of re-discovery.

§ 03Sources

List all run sources

GET/api/v1/sources/{session_id}

Returns every source the run discovered, including those that didn't survive screening. Each record carries scores, selection rationale, and pre-built citations.

Top sources only

GET/api/v1/sources/{session_id}/top10

Returns just the top sources that informed the synthesis phase. Faster and lighter when you only need the survivors.

Save sources to library

POST/api/v1/runs/{run_id}/sources/save

Idempotently saves a run's sources to the user's library. Re-calling is safe — duplicates are deduped by URL.

§ 04Citations

Fetch all citations

GET/api/v1/citations/{session_id}

Returns every citation for the run, in every supported format.

Fetch by format

GET/api/v1/citations/{session_id}/{format}

Returns the run's citations rendered in a specific format.

Param	Type	Required	Description
session_id	string	required	Path parameter. The session ID for the run.
format	string	required	Path parameter. One of `mla`, `apa`, `chicago-notes`, `chicago-author-date`, `ieee`, `harvard`, `bibtex`.

Bulk export

POST/api/v1/citations/{session_id}/export

Returns a bulk archive (ZIP) of citations across formats, with a manifest mapping sources to formats.

§ 05Projects

Project endpoints manage the long-lived workspaces described in Projects & documents.

List projects

GET/api/v1/projects

Returns the projects owned by the authenticated user.

Create a project

POST/api/v1/projects

Creates a new project. Body accepts a name, an optional description, and an optional starting source list.

Project details

GET/api/v1/projects/{project_id}

Returns a project's full record — sources, documents, citation page, metadata.

Update a project

PATCH/api/v1/projects/{project_id}

Patches editable fields on a project (name, description, citation format).

Delete a project

DELETE/api/v1/projects/{project_id}

Removes a project. Sources referenced by the project remain in the user's library; only the project record and its documents are removed.

Project sources & documents

Per-project source and document operations are exposed under nested paths off the project record:

GET/api/v1/projects/{project_id}/sources

POST/api/v1/projects/{project_id}/sources

DELETE/api/v1/projects/{project_id}/sources/{source_id}

GET/api/v1/projects/{project_id}/documents

POST/api/v1/projects/{project_id}/documents

PATCH/api/v1/projects/{project_id}/documents/{document_id}

DELETE/api/v1/projects/{project_id}/documents/{document_id}

TipFor end-to-end integration patterns — including streaming, retries, and pagination — see Integration patterns and Streaming with SSE.