--- title: Mirubiki API: create, launch and read a synthetic survey description: Reference for the Mirubiki public API: API key authentication, surveys, focus groups, response envelope and rate limits. Field names are in French and documented here in English. --- # The Mirubiki API Create a survey, launch it, read the results, run a focus group, from code. The API is the same surface the application uses. Platform administration routes are not published. Request field names are in French (`titre`, `contexte`, `questions`). They stay that way: renaming them would break every existing integration. This page is where they are documented in English. ## Before the first call ### Authentication Every call carries a key in the `X-API-Key` header. Keys are issued on the API page of your dashboard, on the Enterprise and Admin plans only. ### Rate limit 100 requests per minute per key by default. Above that the API answers `429` with `X-RateLimit-Reset`, the number of seconds to wait. ### One host Everything lives under `https://www.mirubiki.com`. There is no separate US endpoint: the panel is the one the account is bound to. ``` curl -H "X-API-Key: mirubi...key" https://www.mirubiki.com/api/v1/surveys ``` ## Response envelope Every endpoint answers the same shape, success or failure. There is no HTTP 200 carrying an error. ``` { "data": { ... }, "error": null } // success { "data": null, "error": "message" } // failure ``` `401` means the key is missing, invalid or revoked. `429` means the limit above. `404` on a survey you do not own is the same answer as a survey that does not exist. ## Surveys A survey is created as a draft, then launched. Results are available once the run is finished; polling the status endpoint is how you know. POST `/api/v1/surveys` Creates a draft. Returns its id and status. ``` curl -X POST -H "X-API-Key: mirubi...key" \ -H "Content-Type: application/json" \ -d '{ "titre": "New checkout flow", "contexte": "We are testing a two-step checkout against the current one.", "questions": [ { "texte": "Which checkout would you complete?", "type": "choix_unique", "options": ["Two-step", "Current", "Neither"] }, { "texte": "What would stop you?", "type": "libre" } ], "nb_personas": 50, "filtres": { "age": ["25-34"], "sex": "F" } }' \ https://www.mirubiki.com/api/v1/surveys ``` | Field | Type | What it does | | --- | --- | --- | | `titre` | string | Survey title. Optional, derived from the context when empty. | | `contexte` | string | What the survey is about. Optional. | | `questions` | array | Required. Each item carries `texte`, `type` and `options`. | | `nb_personas` | int | How many profiles answer. Default 50, between 1 and 100. | | `filtres` | object | Optional demographic selection. | POST `/api/v1/surveys/{id}/launch` Moves a draft to running. A survey already running, done or failed is refused. ``` curl -X POST -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/surveys/abc123/launch ``` GET `/api/v1/surveys/{id}/status` Status and progress. Poll this rather than guessing a delay. ``` curl -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/surveys/abc123/status ``` GET `/api/v1/surveys/{id}/results` Answers of a finished survey. Empty or refused while the run is in progress. ``` curl -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/surveys/abc123/results ``` GET `/api/v1/surveys` Lists your surveys, paged with `limit` and `offset`. ``` curl -H "X-API-Key: mirubi...key" \ "https://www.mirubiki.com/api/v1/surveys?limit=20&offset=0" ``` DELETE `/api/v1/surveys/{id}` Deletes a survey. There is no undelete. ``` curl -X DELETE -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/surveys/abc123 ``` ## Focus groups Two to eight profiles discuss over rounds, moderated by the model. A session is created, then read: there is no separate launch call, turns run when you ask for the transcript. POST `/api/v1/focus` Creates a session and selects its profiles. Returns the session id and the profiles drawn. ``` curl -X POST -H "X-API-Key: mirubi...key" \ -H "Content-Type: application/json" \ -d '{ "titre": "Insurance email review", "guide": "Compare the two proposals", "nb_personas": 4, "max_turns": 6, "filtres": { "sexe": "F", "ages": ["25-40"] } }' \ https://www.mirubiki.com/api/v1/focus ``` | Field | Type | What it does | | --- | --- | --- | | `titre` | string | Session title. | | `guide` | string | Moderator guide, optional. | | `nb_personas` | int | Between 2 and 8, default 6. | | `max_turns` | int | Rounds to run, default 6. | | `filtres` | object | Optional: `ages`, `sexe`, `densites`, `occupations`. | GET `/api/v1/focus` Lists your sessions, paged with `limit` and `offset`. ``` curl -H "X-API-Key: mirubi...key" \ "https://www.mirubiki.com/api/v1/focus?limit=20&offset=0" ``` GET `/api/v1/focus/{id}` One session, with its profiles and settings. ``` curl -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/focus/abc123 ``` GET `/api/v1/focus/{id}/transcript` The discussion as text. Empty until turns have run. ``` curl -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/focus/abc123/transcript ``` DELETE `/api/v1/focus/{id}` Deletes a session, its profiles and its messages. There is no undelete. ``` curl -X DELETE -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/focus/abc123 ``` ## API keys Keys can be managed from code as well as from the dashboard. GET `/api/v1/api-keys` Lists the keys of the account. ``` curl -H "X-API-Key: mirubi...key" https://www.mirubiki.com/api/v1/api-keys ``` POST `/api/v1/api-keys` Creates a key. The secret is returned once: it is not readable afterwards. ``` curl -X POST -H "X-API-Key: mirubi...key" \ -H "Content-Type: application/json" \ -d '{"nom": "production"}' \ https://www.mirubiki.com/api/v1/api-keys ``` DELETE `/api/v1/api-keys/{id}` Revokes a key. Calls already in flight with it are refused at the next request. ``` curl -X DELETE -H "X-API-Key: mirubi...key" \ https://www.mirubiki.com/api/v1/api-keys/42 ``` ## What the API does not do ### No human panel Nothing here fields a questionnaire to real respondents. There is no incidence, no cooperation rate, no field date. ### No population estimate Results are not a share of a population and carry no margin of error. Reporting them as one is a misuse of the tool. ### Filters are selection, not quotas `filtres` picks profiles from the panel. It does not weight them to match a target distribution. ### Answers still need a field check What a synthetic run is good at is finding a defective item or a wording that pushes an answer. Claim-level numbers are a different job. ## For agents and integrations The same surface, written for a machine. - [OpenAPI specification](/openapi-v1.json): the published surface only. Field descriptions in the spec are still in French; paths and schemas are language-neutral. - [API catalog](/.well-known/api-catalog) (RFC 9727): points to this page, the spec and the status endpoint. - [auth.md](/auth.md): how to authenticate, what is refused, how to request access. - [/api/status](/api/status): service state, in JSON. - [llms.txt](/llms.txt): the site map written for an agent. Last updated 18 October 2026.