---
title: "Evidential Experiments API"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.evidential.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Evidential Experiments API

The Experiments API connects your application to the experiments you design in [Evidential](https://app.evidential.dev/).
Your application asks Evidential which arm each participant is in and, for bandit experiments, reports the outcome it
observes.

### Authentication

Every request needs a data source API key in the `X-API-Key` header. Create and manage keys in Evidential under
**Settings**, in the **Data sources** section. Keys begin with `xat`.

```bash
curl https://api.evidential.dev/v1/experiments/<experiment_id> \
  --header 'X-API-Key: <your API key>'
```

### Choose your endpoints

Assignment works the same way for every experiment type: your application asks Evidential which arm a participant
belongs to. What differs is how outcomes reach Evidential:

- **Pull**: Evidential reads outcomes from your data source, and your application reports none.
- **Push**: your application reports each outcome by calling [Record an outcome](https://docs.evidential.dev/api/outcomes/record/).

The endpoints you call depend on the experiment type:

- **Preassigned A/B** (pull): assignments are created when the experiment is designed.
  [List](https://docs.evidential.dev/api/assignments/list/) or [export](https://docs.evidential.dev/api/assignments/export-csv/) them all, or
  [look up one participant's](https://docs.evidential.dev/api/assignments/retrieve/) at runtime.
- **Online A/B** (pull): [get or create an assignment](https://docs.evidential.dev/api/assignments/retrieve/) as each participant arrives, or
  [assign with filters](https://docs.evidential.dev/api/assignments/assign-with-filters/) if the experiment uses server-side filtering.
- **Multi-armed bandit, MAB** (push): [get or create an assignment](https://docs.evidential.dev/api/assignments/retrieve/), then
  [record its outcome](https://docs.evidential.dev/api/outcomes/record/).
- **MAB with a data warehouse outcome** (pull, `mab_online_dwh`): [get or create an
  assignment](https://docs.evidential.dev/api/assignments/retrieve/). Evidential reads each outcome from the column bound to the experiment.
- **Contextual multi-armed bandit, CMAB** (push): [assign with context values](https://docs.evidential.dev/api/assignments/assign-cmab/), then
  [record its outcome](https://docs.evidential.dev/api/outcomes/record/).

To keep your own systems in sync with Evidential, [list the experiments on a data source](https://docs.evidential.dev/api/experiments/list/) and
[get an experiment's design](https://docs.evidential.dev/api/experiments/retrieve/).

### Errors

Branch on the HTTP status code, not on the text of the error message: status codes are stable, but message text may
change. `2xx` codes mean success, `4xx` codes usually mean a problem with your request, and `5xx` codes mean a
server-side error that may be retried.

### Retries

Retry only transient failures: network errors and `5xx` responses. Use exponential backoff with jitter, and cap the
number of attempts. Don't retry `4xx` responses; they fail again until you change the request, or until the
experiment, data source, or assignment changes. Assignment requests are safe to retry, because they return the existing
assignment when one was already created.

Version: 0.9.0

## Servers

- `https://api.evidential.dev`

## [Experiments](https://docs.evidential.dev/api/tags/experiments/)

Look up the experiments on a data source and their designs.

- [List experiments on a data source](https://docs.evidential.dev/api/experiments/list/) — `GET /v1/experiments`
- [Get an experiment's design](https://docs.evidential.dev/api/experiments/retrieve/) — `GET /v1/experiments/{experiment_id}`

## [Assignments](https://docs.evidential.dev/api/tags/assignments/)

Get or create participants' arm assignments, and list or export an experiment's assignments.

- [Get or create a participant's assignment](https://docs.evidential.dev/api/assignments/retrieve/) — `GET /v1/experiments/{experiment_id}/assignments/{participant_id}`
- [Get or create an Online A/B assignment with server-side filtering](https://docs.evidential.dev/api/assignments/assign-with-filters/) — `POST /v1/experiments/{experiment_id}/assignments/{participant_id}/assign_with_filters`
- [Get or create a CMAB assignment for a participant](https://docs.evidential.dev/api/assignments/assign-cmab/) — `POST /v1/experiments/{experiment_id}/assignments/{participant_id}/assign_cmab`
- [List an experiment's assignments](https://docs.evidential.dev/api/assignments/list/) — `GET /v1/experiments/{experiment_id}/assignments`
- [Export an experiment's assignments as CSV](https://docs.evidential.dev/api/assignments/export-csv/) — `GET /v1/experiments/{experiment_id}/assignments/csv`

## [Outcomes](https://docs.evidential.dev/api/tags/outcomes/)

Report the outcomes of bandit experiments that use push integration.

- [Record a bandit arm outcome for a participant](https://docs.evidential.dev/api/outcomes/record/) — `POST /v1/experiments/{experiment_id}/assignments/{participant_id}/outcome`


Source: https://docs.evidential.dev/api/index.md
