# Mida Developer Docs

> Mida is an A/B testing and personalization platform. These docs cover the V2 REST API, the remote MCP server, and the server-side and mobile SDKs (Node.js, Python, Go, PHP, Ruby, Next.js, Vue, Flutter, iOS, Android).

- API base URL: `https://api-us.mida.so` or `https://api-eu.mida.so`, matching the project's data region.
- Auth: `Authorization: Bearer <API key>`, generated in the Mida dashboard under Projects → [your project] → Settings → API. Every project-scoped endpoint takes the project key in its path.
- Experiments created through the API start as drafts. Launching one makes it visible to site visitors.
- Machine-readable spec: [OpenAPI 3](https://docs.mida.so/openapi.json)

## Guides

- [Introduction](https://docs.mida.so/docs/intro): What the API, MCP server and SDKs cover, and where to start.
- [Client-side Quickstart](https://docs.mida.so/docs/quickstart): Create, launch, read and stop a website experiment with curl.
- [MCP Integration](https://docs.mida.so/docs/mcp-integration): Connect Claude, Cursor or another MCP client to Mida over remote OAuth (`https://mcp.mida.so/mcp`).
- [Server-side Testing Overview](https://docs.mida.so/docs/server-side/overview): Client-side vs server-side experiments and when to use each.
- [Server-side Quickstart](https://docs.mida.so/docs/server-side/quickstart): Run a first server-side experiment with an SDK.
- [SDK Catalog](https://docs.mida.so/docs/server-side/sdks): Install and use every official SDK (`getExperiment`, `setEvent`, `isFeatureEnabled`).

## V2 API Reference

### Account

- [Get My Access](https://docs.mida.so/docs/v2/get-my-access): `GET /v2/project/{project_key}/account/my-access` — The caller's own effective role on this project: what they are allowed to do, and why. Answers 'am I view-only?' for the current connection.
- [List Team Members](https://docs.mida.so/docs/v2/list-team-members): `GET /v2/project/{project_key}/account/members` — Everyone on the account that owns this project, with their role, whether they can make changes, membership kind, status and last login. Read-only: roles are managed under Team settings in the dashboard.

### Projects

- [Claim Agent Account](https://docs.mida.so/docs/v2/claim-agent-account): `POST /v2/agent/claim` — Step 2 of creating a Mida account from an AI agent. Send the 6-digit code the person received by email. Mida creates the account and its first project, and returns an API key and the project key.
- [Create Project](https://docs.mida.so/docs/v2/create-project): `POST /v2/project/{project_key}/projects` — Create a new project (website / app) under the same Mida account as the supplied project key. The new project's project_key is auto-generated and returned — use it to install the Mida script on the new site, then mint API keys via the dashboard if needed.
- [Delete Project](https://docs.mida.so/docs/v2/delete-project): `DELETE /v2/project/{project_key}` — Soft-delete a project. The project disappears from list / get responses but all experiments, events, and visitor data are retained for billing, history, and compliance. There is no hard-delete endpoint — for a permanent wipe (e.g. GDPR) contact Mida support.
- [Get Global Custom Code](https://docs.mida.so/docs/v2/get-global-custom-code): `GET /v2/project/{project_key}/global-custom-code` — Return the project's Global Custom Code: JavaScript and CSS that already run on every page with the Mida pixel. Empty strings mean nothing is set yet. Call this before appending a custom-event snippet so existing code is kept.
- [Get Install Health](https://docs.mida.so/docs/v2/get-install-health): `GET /v2/project/{project_key}/install-health` — Check whether the Mida tag on this project's site is installed and sending visitors. Call it after installing the tag and before building an experiment: a test on a site with no working tag collects nothing.
- [Get Project Configuration](https://docs.mida.so/docs/v2/get-project-configuration): `GET /v2/project/{project_key}/configuration` — Return project-level Global Settings: default primary goal, secondary metrics, stats engine, and confidence threshold. Experiments without an attached primary goal use this default when you call Get Experiment Result or Get Experiment Timeseries without goal_key.
- [Get Project Details](https://docs.mida.so/docs/v2/get-project-details): `GET /v2/project/{project_key}` — Return details for a single project. The API key must be valid for the supplied project key (or any sibling project under the same company).
- [List Projects](https://docs.mida.so/docs/v2/list-projects): `GET /v2/project/{project_key}/projects` — Return every project (website / app) under the same Mida account as the supplied project key. The project key in the URL is used purely as auth context — you'll receive the full list of sibling projects, including the one matched by that key. Lets an external client (e.g. an AI agent) discover and switch between projects.
- [Register Agent Account](https://docs.mida.so/docs/v2/register-agent-account): `POST /v2/agent/register` — Step 1 of creating a Mida account from an AI agent, for a person who does not have one yet. Mida emails that person a 6-digit code. No account is created until the code is sent back with Claim Agent Account. No API key is needed.
- [Update Global Custom Code](https://docs.mida.so/docs/v2/update-global-custom-code): `PATCH /v2/project/{project_key}/global-custom-code` — Install JavaScript or CSS into Global Custom Code, which already runs on every page with the Mida pixel. Prefer append_js / append_css so existing code is kept. Use js / css only when you mean to replace the whole file. This is how a custom event is installed without changing the customer's site.
- [Update Project Configuration](https://docs.mida.so/docs/v2/update-project-configuration): `PATCH /v2/project/{project_key}/configuration` — Update project-level Global Settings: the default primary goal, secondary metrics, stats engine, and confidence level that every newly created experiment inherits. Partial update: send only the fields you want to change. Existing experiments are not touched.
- [Update Project](https://docs.mida.so/docs/v2/update-project): `PATCH /v2/project/{project_key}` — Update mutable fields on a project. Only the whitelisted fields below are accepted — anything else in the body is silently ignored, so the API surface stays predictable.

### Experiments

- [Add Experiment Comment](https://docs.mida.so/docs/v2/add-experiment-comment): `POST /v2/project/{project_key}/experiment/{test_id}/discussion` — Post a comment to the Discussion on an experiment's report. The test's assigned members are notified by email, exactly as for a comment made in the dashboard. Requires a signed-in author (an MCP connection); plain API keys can read the thread but not post.
- [Create Experiment](https://docs.mida.so/docs/v2/create-experiment): `POST /v2/project/{project_key}/create-experiment` — Create a new A/B experiment for a project. The experiment is created in draft status by default.
- [Delete Experiment Comment](https://docs.mida.so/docs/v2/delete-experiment-comment): `DELETE /v2/project/{project_key}/experiment/{test_id}/discussion/{comment_id}` — Delete one comment from an experiment's Discussion. Allowed for the comment's own author, or an Owner/Admin moderating the thread.
- [Delete Experiment](https://docs.mida.so/docs/v2/delete-experiment): `DELETE /v2/project/{project_key}/experiment/{test_id}` — Delete an experiment. It disappears from the Experiments list and, if it was running, stops being served to visitors.
- [Get Experiment Details](https://docs.mida.so/docs/v2/get-experiment-details): `GET /v2/project/{project_key}/experiment/{test_id}` — Return full details for one experiment, including its variants, goals, targeting rules, and configuration.
- [Get Experiment Discussion](https://docs.mida.so/docs/v2/get-experiment-discussion): `GET /v2/project/{project_key}/experiment/{test_id}/discussion` — The Discussion thread on an experiment's report: every comment with its author, time, and whether it was edited. This is where teams record decisions and caveats next to the numbers.
- [Get Experiment Distribution](https://docs.mida.so/docs/v2/get-experiment-distribution): `GET /v2/project/{project_key}/experiment/{test_id}/distribution` — Return configured per-variant traffic splits for an experiment — a compact alternative to Get Experiment Details when you only need allocation weights.
- [Get Experiment Metrics](https://docs.mida.so/docs/v2/get-experiment-metrics): `GET /v2/project/{project_key}/experiment/{test_id}/metrics` — Return dashboard-parity secondary metric rows for an experiment, with optional metric selection, date filtering, and dashboard-compatible filters.
- [Get Experiment Preview URLs](https://docs.mida.so/docs/v2/get-experiment-preview-urls): `GET /v2/project/{project_key}/experiment/{test_id}/preview-urls` — Return ready-to-share preview links for every variant of an experiment — Control plus all treatments. Each link forces the requested variant to render regardless of the visitor's normal bucketing or any active segment rules. Useful for QA, customer-support flows, or stakeholder review before launch.
- [Get Experiment Result](https://docs.mida.so/docs/v2/get-experiment-result): `GET /v2/project/{project_key}/experiment/{test_id}/result` — Return dashboard-parity conversion results for an experiment, with optional goal drilldowns, dashboard-compatible filters, and breakdowns.
- [Get Experiment Share Link](https://docs.mida.so/docs/v2/get-experiment-share-link): `GET /v2/project/{project_key}/experiment/{test_id}/share-link` — Return the public share link for an experiment's results page. Share links let anyone view experiment results without logging in.
- [Get Experiment Timeseries](https://docs.mida.so/docs/v2/get-experiment-timeseries): `GET /v2/project/{project_key}/experiment/{test_id}/timeseries` — Return dashboard-parity daily chart rows for an experiment using the same backend raw report engine as the Mida dashboard.
- [Get Pre-Publish Check](https://docs.mida.so/docs/v2/get-pre-publish-check): `GET /v2/project/{project_key}/experiment/{test_id}/pre-publish-check` — Run Mida's setup rules over a saved experiment before launching it: the same checks the dashboard runs on each step of the experiment wizard. Returns what blocks launch and what is worth a second look. It changes nothing.
- [Link Hypothesis to Experiment](https://docs.mida.so/docs/v2/link-hypothesis-to-experiment): `POST /v2/project/{project_key}/experiment/{test_id}/hypothesis` — Attach a hypothesis to an existing experiment, so its result reads against what it was meant to prove. Send hypothesis_id 0 to detach.
- [List Experiments](https://docs.mida.so/docs/v2/list-experiments): `GET /v2/project/{project_key}/experiments` — Return all experiments for the company tied to the provided project key. Supports pagination.
- [Serve Experiment Winner](https://docs.mida.so/docs/v2/serve-experiment-winner): `POST /v2/project/{project_key}/experiment/{test_id}/serve-winner` — Set winner and serve the winning variant at 100% on the same experiment — the API equivalent of the dashboard Set winner & serve. Does not create a separate deploy test.
- [Stop Experiment Serving](https://docs.mida.so/docs/v2/stop-experiment-serving): `POST /v2/project/{project_key}/experiment/{test_id}/stop-serving` — Stop serving the winner at 100% on an experiment. Clears serving_variant_id so visitors are no longer forced to the winning variant.
- [Update Experiment Status](https://docs.mida.so/docs/v2/update-experiment-status): `PATCH /v2/project/{project_key}/experiment/{test_id}/status` — Start, pause, or deactivate an experiment by updating its status. This is the primary way to control an experiment's lifecycle via the API.
- [Update Experiment](https://docs.mida.so/docs/v2/update-experiment): `PATCH /v2/project/{project_key}/experiment/{test_id}` — Update an experiment's name, URL, variants, configuration, custom code, targeting, or secondary metrics. Only fields you include are changed; all other fields remain unchanged.
- [Update Serving Rollout](https://docs.mida.so/docs/v2/update-serving-rollout): `PATCH /v2/project/{project_key}/experiment/{test_id}/serving-rollout` — Change the rollout percentage for an experiment that is already serving a winner. Updates traffic_allocation without changing which variant is served.

### Goals

- [Create Goal](https://docs.mida.so/docs/v2/create-goal): `POST /v2/project/{project_key}/goal` — Create a goal profile for the selected project. Goals define what counts as a conversion: page visits, clicks, forms, scroll depth, events, revenue, or manual triggers.
- [Delete Goal](https://docs.mida.so/docs/v2/delete-goal): `DELETE /v2/project/{project_key}/goal/{goal_profile_id}` — Soft-delete a goal profile. The record is preserved in the database but will no longer appear in the Goals list or be selectable for new experiments.
- [Get Goal Details](https://docs.mida.so/docs/v2/get-goal-details): `GET /v2/project/{project_key}/goal/{goal_profile_id}` — Return the full definition of a single goal profile by its ID.
- [List Goals](https://docs.mida.so/docs/v2/list-goals): `GET /v2/project/{project_key}/goals` — Return all goal profiles for the selected project. Goals define what counts as a conversion in your experiments.
- [Update Goal](https://docs.mida.so/docs/v2/update-goal): `PATCH /v2/project/{project_key}/goal/{goal_profile_id}` — Update fields on a goal profile. Only the fields you include are changed — all other fields remain unchanged.

### Events

- [Create Event](https://docs.mida.so/docs/v2/create-event): `POST /v2/project/{project_key}/event` — Record a custom event for a specific visitor. The event is tied to a visitor record in Mida — identify the visitor using their Mida UUID, email, or your own user ID.
- [Delete Event](https://docs.mida.so/docs/v2/delete-event): `DELETE /v2/project/{project_key}/event/{event_id}` — Soft-delete an event by setting its status to inactive. The event record is preserved in the database but will no longer appear in the Events dashboard or API list responses.
- [Get Event Details](https://docs.mida.so/docs/v2/get-event-details): `GET /v2/project/{project_key}/event/{event_id}` — Return the full details of a single event by its ID.
- [List Events](https://docs.mida.so/docs/v2/list-events): `GET /v2/project/{project_key}/events` — Return all custom events for the selected project. Only active, non-internal events are returned — mirrors the Events dashboard view.
- [Update Event](https://docs.mida.so/docs/v2/update-event): `PATCH /v2/project/{project_key}/event/{event_id}` — Update fields on a single event. Only the fields you include are changed — all other fields remain unchanged.

### Hypotheses

- [Create Hypothesis](https://docs.mida.so/docs/v2/create-hypothesis): `POST /v2/project/{project_key}/hypotheses` — Add an idea to the project's backlog, with the reasoning behind it and how you rate it.
- [Delete Hypothesis](https://docs.mida.so/docs/v2/delete-hypothesis): `DELETE /v2/project/{project_key}/hypotheses/{hypothesis_id}` — Remove an idea from the backlog. A hypothesis that experiments were run from cannot be deleted.
- [Get Hypothesis Details](https://docs.mida.so/docs/v2/get-hypothesis-details): `GET /v2/project/{project_key}/hypotheses/{hypothesis_id}` — Return one hypothesis, including every experiment that has been run from it.
- [List Hypotheses](https://docs.mida.so/docs/v2/list-hypotheses): `GET /v2/project/{project_key}/hypotheses` — Return the project's hypothesis backlog: the ideas the team wrote down, how they rated each one, and which experiments came out of them.
- [Update Hypothesis](https://docs.mida.so/docs/v2/update-hypothesis): `PATCH /v2/project/{project_key}/hypotheses/{hypothesis_id}` — Change the wording or the ratings on an existing hypothesis. Fields you leave out are not touched.

### Personalization

- [Add Accounts to a Personalization Campaign](https://docs.mida.so/docs/v2/add-personalization-accounts): `POST /v2/project/{project_key}/personalization/campaigns/{campaign_id}/accounts` — Add companies to a campaign that already exists and get each one's link back immediately. The link is final on return, so it is safe to store or send straight away; the researched copy lands behind that same URL over the following minutes.
- [Create Personalization Campaign](https://docs.mida.so/docs/v2/create-personalization-campaign): `POST /v2/project/{project_key}/personalization/campaigns` — Build a new Personalization campaign. Two strategies: accounts researches named companies and writes copy for each, personas writes one version per job role with no company list and no research. Returns a campaign to open, not a finished campaign, and never publishes.
- [Get Personalization Campaign](https://docs.mida.so/docs/v2/get-personalization-campaign): `GET /v2/project/{project_key}/personalization/campaigns/{campaign_id}` — One campaign in enough detail to answer how a build is going and what is left: the stage it reached, how many accounts were researched and had copy written, which failed and why, and whether it still needs a goal before it can be launched.
- [List Personalization Campaigns](https://docs.mida.so/docs/v2/list-personalization-campaigns): `GET /v2/project/{project_key}/personalization/campaigns` — This project's Personalization campaigns, newest first, with how many accounts each has, how many already have copy, and whether it is building or launched. Call this to find a campaign_id before adding accounts to one.
- [List Saved Target Accounts](https://docs.mida.so/docs/v2/list-saved-target-accounts): `GET /v2/project/{project_key}/personalization/saved-accounts` — Companies this project has targeted before, most recently used first. An account already listed has been researched already, so reusing it is cheaper and starts warm.
- [Suggested Pages to Personalize](https://docs.mida.so/docs/v2/personalization-suggested-pages): `GET /v2/project/{project_key}/personalization/suggested-pages` — Which of your own pages are worth personalizing, ranked, with a reason each. Candidates come from your real traffic over the last 60 days, so these are pages that exist and get visited.
- [Set the Goal on a Personalization Campaign](https://docs.mida.so/docs/v2/set-personalization-goal): `PATCH /v2/project/{project_key}/personalization/campaigns/{campaign_id}` — Attach a goal to a campaign that already exists, or change the one it has. A campaign cannot be launched without a goal, and a campaign created without one reports needs_goal until this is called.

### Exclusion groups

- [Create Exclusion Group](https://docs.mida.so/docs/v2/create-exclusion-group): `POST /v2/project/{project_key}/exclusion-groups` — Make a set of experiments mutually exclusive: each visitor is assigned to exactly one of them, by traffic split. Use this when experiments overlap on the same page or audience — the answer to overlap is a group, not fewer tests.
- [Delete Exclusion Group](https://docs.mida.so/docs/v2/delete-exclusion-group): `DELETE /v2/project/{project_key}/exclusion-groups/{group_id}` — Remove a mutually exclusive group. The experiments in it keep running — they just stop being exclusive, so a visitor can enter more than one of them again.
- [List Exclusion Groups](https://docs.mida.so/docs/v2/list-exclusion-groups): `GET /v2/project/{project_key}/exclusion-groups` — List the project's mutually exclusive groups. A group splits traffic so each visitor enters exactly one of its experiments, keeping tests that share a page from contaminating each other's results.
- [Update Exclusion Group](https://docs.mida.so/docs/v2/update-exclusion-group): `PATCH /v2/project/{project_key}/exclusion-groups/{group_id}` — Change an exclusion group's membership, splits, name or description. The tests array REPLACES the whole membership — to add one experiment, send the existing tests plus the new one.

### Surveys

- [Create Survey](https://docs.mida.so/docs/v2/create-survey): `POST /v2/project/{project_key}/create-survey` — Create an on-site survey as a draft. Nobody sees it until you set it live.
- [Delete Survey](https://docs.mida.so/docs/v2/delete-survey): `DELETE /v2/project/{project_key}/survey/{survey_id}` — Archive a survey: off the site and off the list. Its answers stay.
- [Get Survey Details](https://docs.mida.so/docs/v2/get-survey-details): `GET /v2/project/{project_key}/survey/{survey_id}` — One survey: its questions and branching, when it asks, its look, limits and page targeting.
- [Get Survey Responses](https://docs.mida.so/docs/v2/get-survey-responses): `GET /v2/project/{project_key}/survey/{survey_id}/responses` — One row per person who answered, newest first, with where they came from.
- [Get Survey Results](https://docs.mida.so/docs/v2/get-survey-results): `GET /v2/project/{project_key}/survey/{survey_id}/results` — The survey's report: the funnel and every question's answers, filtered to a group or compared across groups.
- [List Surveys](https://docs.mida.so/docs/v2/list-surveys): `GET /v2/project/{project_key}/surveys` — The project's on-site surveys, with how many people saw and answered each.
- [Update Survey Status](https://docs.mida.so/docs/v2/update-survey-status): `PATCH /v2/project/{project_key}/survey/{survey_id}/status` — Set a survey live, pause it, or end it.
- [Update Survey](https://docs.mida.so/docs/v2/update-survey): `PATCH /v2/project/{project_key}/survey/{survey_id}` — Change a survey's questions, settings or targeting. Only the fields you send change.