# REST API URL: https://docs.ablyft.com/developers/reference/rest-api/ > Manage experiments and read results programmatically with the ABlyft REST API. The REST API lets scripts and other systems work with ABlyft: list projects and experiments, create or change experiments, start and pause them, and read results. Requests and responses use JSON. The base URL is `https://app.ablyft.com/api`. A complete, interactive reference of all endpoints with their parameters is available at [https://app.ablyft.com/docs/api](https://app.ablyft.com/docs/api). ## Authentication Every request needs an **API token** in the `Authorization` header: ```text Authorization: Bearer YOUR_TOKEN Accept: application/json ``` ### Create a token 1. Open your personal settings and go to **API Tokens**. 2. Click **Create token**. 3. Enter a **Name** (shown in your token list) and choose the **Permissions**: | Permission | Allows | | ---------------- | --------------------------------------------- | | **Read only** | Reading data (`GET` requests) | | **Read & write** | Reading, creating, changing and deleting data | 4. Copy the token from the dialog. **It is shown only once.** The token list shows each token's name, abilities, when it was last used and when it was created. Use **Revoke** to delete a token. A token does not expire on its own. A token works for all teams you are a member of, with the permissions of your role in each team, see [Roles & permissions](https://docs.ablyft.com/guides/projects-and-teams/roles-and-permissions/). A request with a missing ability returns `403` with the message "Missing required ability: read" (or `write`). > **Keep tokens secret:** Never put a token into front-end code or a public repository. See [Security](https://docs.ablyft.com/developers/consent-and-security/security/). ## Rate limit Requests are limited per user, per minute. By default, a user can make 60 requests per minute. If you exceed the limit, the API answers with HTTP status `429`. Wait a moment and retry. Contact ABlyft support if you need a higher limit. ## Endpoints IDs in paths are numeric. `{project}` is the project ID, `{experiment}` the experiment ID. | Resource | Method and path | Purpose | | ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Teams | `GET /teams` | Teams you belong to | | | `GET /teams/{team}/projects` | Projects of a team | | Projects | `GET /projects/{project}` | Show a project | | | `PUT/PATCH /projects/{project}` | Update `name`, `description`, `significance`, `min_conversions`, `min_runtime_days` | | | `DELETE /projects/{project}` | Delete a project | | | `POST /projects/{project}/{model}/find-by-name` | Find an item by its exact `name`. `{model}` is `experiments`, `audiences`, `pages`, `goals` or `environments` | | Experiments | `GET /projects/{project}/experiments` | List experiments (optional `?variations=lite`) | | | `POST /projects/{project}/experiments` | Create an experiment | | | `GET /projects/{project}/experiments/{experiment}` | Show an experiment | | | `PUT/PATCH /projects/{project}/experiments/{experiment}` | Update name, API name, description, example URL, traffic allocation and attached audiences, pages, goals and environments | | | `DELETE /projects/{project}/experiments/{experiment}` | Delete an experiment | | | `POST /projects/{project}/experiments/{experiment}/clone` | Clone an experiment | | | `PATCH /projects/{project}/experiments/{experiment}/status` | Change the status | | | `PATCH /projects/{project}/experiments/{experiment}/publish` | Publish the project | | Variations | `/projects/{project}/experiments/{experiment}/variations` | List, create, show, update, delete | | Audiences | `/projects/{project}/audiences` | List, create, show, update, delete | | Pages | `/projects/{project}/pages` | List, create, show, update, delete | | Goals | `/projects/{project}/goals` | List, create, show, update, delete | | Environments | `GET /projects/{project}/environments` and `.../{environment}` | Read only | | Results | `GET /projects/{project}/experiments/{experiment}/results` | Statistics per goal | | | `GET .../results/info` | Share token and share URL of the results | | | `GET .../results/goal/{goal}` | Event series of one goal | | | `GET .../results/goal/{goal}/download` | The same as CSV file | For the standard resources (variations, audiences, pages, goals) use the usual methods: `GET` to list or show, `POST` to create, `PUT`/`PATCH` to update and `DELETE` to delete. Creating, updating and deleting needs a **Read & write** token and the permission of your role. There is no endpoint that lists all projects at once. First read your teams, then the projects of each team. ### Change the status of an experiment Send one of `draft`, `preview`, `running`, `pause` or `archive` as `status`: ```bash curl -X PATCH https://app.ablyft.com/api/projects/12345678/experiments/23456789/status \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"status": "running"}' ``` The response contains the updated experiment. Make sure the experiment has at least one variation, page and goal before you start it, as in the app, see [Before you can preview or start](https://docs.ablyft.com/guides/experiments/start-pause-stop/#before-you-can-preview-or-start). ### Reduce the response On experiment requests, add `?fields=id,name,status` to get only these fields. ## Examples ### List your teams and projects ```bash curl https://app.ablyft.com/api/teams \ -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" ``` ```json [ { "id": 1234, "name": "My company", "created_at": "2025-01-15T09:30:00.000000Z", "updated_at": "2025-06-01T12:00:00.000000Z" } ] ``` ```bash curl https://app.ablyft.com/api/teams/1234/projects \ -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" ``` The response lists each project with fields such as `id`, `name`, `storage`, `snippet_revision` and `snippet_version`. ### List experiments ```bash curl "https://app.ablyft.com/api/projects/12345678/experiments?fields=id,name,status" \ -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" ``` ```json [ { "id": 23456789, "name": "Product page: bigger buy button", "status": "running" } ] ``` Without `fields`, each experiment also contains `description`, `example_url`, `traffic_allocation`, `audiences_match_type`, `tags`, `js`, `reset_js`, `css`, and the `variations`. ### Read results ```bash curl https://app.ablyft.com/api/projects/12345678/experiments/23456789/results \ -H "Authorization: Bearer YOUR_TOKEN" -H "Accept: application/json" ``` The response is a list with one entry per goal (abbreviated here). `variationStatistics` is keyed by variation ID: ```json [ { "id": 34567890, "type": "custom", "name": "Newsletter signup", "api_name": "newsletter-signup", "variationStatistics": { "87654321": { "id": 87654321 } } } ] ``` The statistics object of each variation contains participants, conversions, values and the significance figures that the results page shows. The fields are listed in the interactive reference. The optional query parameters `startDate`, `endDate` and `deviceTypes` filter the results. If an experiment has no results yet, the API answers with `404` and "No result found for this experiment". ## Errors | Status | Meaning | | ------ | ------------------------------------------------------------------- | | `401` | Missing or invalid token | | `403` | The token lacks the ability, or your role does not allow the action | | `404` | The item does not exist, or you cannot see it | | `422` | Validation failed. The response lists the fields | | `429` | Rate limit reached | ## Next steps - [MCP server](https://docs.ablyft.com/developers/reference/mcp-server/): Let an AI assistant use ABlyft for you. - [Security](https://docs.ablyft.com/developers/consent-and-security/security/): Keep your tokens safe.