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.
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 paid-action scopes. 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 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 available wallet balance. 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.

Current output formats

The public API exposes structured reports, transcript segments, private CSV or JSONL interview exports, editable report slide decks, and saved Highlights videos. Use the persisted report and interview endpoints for current integrations.