API access
Which door opens what: the REST API for people and links, the MCP server for everything else, and what stays on screen.
Choose the right door
| Surface | Access and scope |
|---|---|
| REST API | An API key as a bearer. Add people to a study, prepare and download personal links, name one person, read the list, read and change a study's shareable links. See the REST API. |
| MCP server | The same key. List, read, create and update studies, guides, audiences and recruitment plans; read fieldwork, quality, reports and analysis. See the MCP server. |
| Customer draft API | GET and POST /api/research/customer/studies exist for isolated local review only; hosted use is not enabled. |
| Legacy /api/v1 | Studio's study and participant runtime with its uh_live key; not a Research contract. |
One key, two doors A Research API key is made in Settings by any member, acts as that member in one workspace, and carries a read or a read-and-edit scope. A Studio uh_live key does not open Research.
What stays on screen
Launching a study and ordering panel respondents move money, so they stay on Recruit. Sending messages to your own people, deleting a list and opting a person out stay on screen, where the researcher sees the count and the message before pressing. A key that asks for one of these gets a 403 that says so.
Everything a key can do, it does exactly as the researcher could on screen, in the one workspace the key belongs to. Studies from another workspace do not exist as far as the key is concerned.
Credentials and retries
- Keep keys in the service's secret store or environment, never in client code or shared documents.
- Prefer a read key wherever edits are not needed, and name keys per tool so one can be revoked alone.
- Keep one stable idempotency key for the same operation and input over MCP, and reuse it on retry.
- After a conflict or an uncertain outcome, read the saved state before retrying.
- Respect rate limits and read the error body: it says in plain words what to change.