API keys
API reference
The HTTP endpoints behind the MCP tools, for scripts that call PopsicleAI directly.
Every endpoint takes an API key in the Authorization: Bearer header and returns JSON. The base URL is https://popsicleai.app.
curl https://popsicleai.app/api/mcp/studies \
-H "Authorization: Bearer ak_your_key_here"Studies
| Method and path | What it does |
|---|---|
GET /api/mcp/studies | Your studies across workspaces. ?limit= up to 100 (50 by default). |
POST /api/mcp/studies | Create a study. Body: title, description, agent_instructions, and optionally participant_instructions, website_url, interview_mode (voice or chat), interview_languages, max_duration (5 to 30), max_participants (1 to 100), workspace_id. |
GET /api/mcp/studies/{id} | One study, with its participant link. |
PATCH /api/mcp/studies/{id} | Change the fields you send. |
DELETE /api/mcp/studies/{id} | Delete the study and its recordings. |
Interview guides
| Method and path | What it does |
|---|---|
POST /api/mcp/study-guide/draft | Draft a guide. Body: description (20 to 1,000 characters), optional title, focus, interview_mode, max_duration, stimuli_titles. |
POST /api/mcp/study-guide/review | Flag biased questions. Body: guide, optional title, description. |
Recordings and transcripts
| Method and path | What it does |
|---|---|
GET /api/mcp/studies/{id}/recordings | A study’s sessions. ?limit= up to 100. |
GET /api/mcp/recordings/{id} | One recording with its transcript. |
DELETE /api/mcp/recordings/{id} | Delete a recording. |
GET /api/mcp/studies/{id}/transcripts | Every transcript in a study. |
Findings and billing
| Method and path | What it does |
|---|---|
GET /api/mcp/studies/{id}/summary | Participation stats and the AI findings. |
POST /api/mcp/studies/{id}/findings | Start generating findings. |
POST /api/mcp/studies/{id}/share | Public findings link. Body: enabled, show_names, include_clips. |
GET /api/mcp/billing | Your minutes balance, plan and recent usage. |
Limits
- About 60 requests a minute per account. Past that you get HTTP 429; wait a moment and retry.
- Findings: up to 20 runs an hour. Drafting and reviewing guides: up to 30 an hour.
- Errors come back as JSON with an
errormessage and a matching HTTP status.
Still stuck?
Write to us and a person will get back to you, usually within one business day.