Skip to main content

​
Start with a reviewable study

An agent can create a draft, help design its interview plan, invite participants, and retrieve evidence. The researcher should review the saved plan and the current recruitment estimate before fieldwork starts. Use an API key with read and write scopes for draft work; paid panel launch also requires panel:launch and a positive lifetime spend cap.
1

Create a draft

Call POST /api/public/v1/studies/ with an Idempotency-Key. Save the returned study ID. See the study lifecycle for state transitions.
2

Design the plan

Call POST /api/public/v1/studies/{study_id}/customize-plan once per conversation turn. Relay returned questions[] when decisions is human. If the researcher delegates ordinary design choices with decisions: "agent", show the returned assumptions[] and any remaining questions. Review the persisted plan before recruiting.
3

Choose recruitment

For your own participants, create invitations or a share link. For a paid panel, request the current estimate, show the amount and target to the researcher, then launch with a key that has the required scope and spend cap. The plan customization call never starts recruitment.
4

Follow progress and evidence

Poll fielding progress and report jobs, or subscribe to webhook events. Retrieve the persisted report and source interviews. Keep interview IDs and source references with each answer; distinguish quotations from analysis and recommendations.
The runnable TypeScript examples include a fixture mode that uses fictional data and makes no network calls. Start there, then validate the narrow live path your application needs with an authorized test study.

​
Connect through MCP

The MCP setup guide covers authentication and tool discovery. Discover the tool schema at runtime, because MCP and REST names or response shapes can differ. The default tool surface includes write operations; use API key scopes and spend caps to limit what a connected agent can do.

​
Evaluate before a live launch

Use a fixed set of realistic briefs and record the study ID, request IDs, tool calls, final plan, estimate, and source references for each run. Include cases with missing audience details, a returned planning question, an uncertain write response, an empty study, and a paid panel estimate that exceeds the key’s cap. Count passes and failures by scenario, retain failed traces, and rerun the same set when the API contract, tool surface, or agent prompt changes. Fixture results demonstrate integration behavior; they do not establish real research quality. The examples release checklist covers response shapes, pagination, citations, and source access.

​
Current output formats

The public API exposes structured reports, transcript segments, and private CSV or JSONL interview exports. Downloadable highlight clips and slide decks are still under development. Use the persisted report and interview endpoints for current integrations.