Skip to main content
Seneca accepts research over the REST API and over MCP. This page is the REST path. It takes a workspace from an API key to a stored research report. The create request returns as soon as the run is accepted. Poll with a new request. Do not keep the original POST open. MCP uses the same key, panels, and credit ledger.

Prerequisites

Reads work without an active subscription. Paid research requires entitled: true and enough available_credits.

Launch a run

1

Store the key

The secret starts with seneca_sk_ and is shown once. Keep it in an environment variable.
2

Read the account

Confirm entitled is true and available_credits covers the panel. Wide Research reserves 15 credits.
3

Create research

POST /v1/research requires Content-Type: application/json and Idempotency-Key. A new run returns 202. Store id.
4

Poll until the run finishes

Research often takes several minutes.
Stop when status is completed, partial, or failed. In-progress statuses are queued, running, and synthesizing.
5

Read the report

Quote the URL so the shell does not treat ? as a pattern.
Read the finding from report.answer. This read does not start research and does not write a credit charge.
If the create response is lost, repeat the same POST with the same Idempotency-Key, prompt, and panel. For 24 hours the server returns the original run and does not charge again.

Next

MCP

Call the same research engine from a Streamable HTTP client.

Polling

Statuses, phase, and progress counts.

Results

Full and compact reports.

Agents

A REST lifecycle, plus MCP for an agent client.

Errors

Read error.code before you retry.