> For the complete documentation index, see [llms.txt](https://docs.three.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.three.dev/api-reference/assign-session.md).

# Assign Session

Assign a session to a specific variant of a running live experiment. If no experiment is running for the provided use case, or if the control variant is selected, the response body is `null`.

{% hint style="info" %}
Assignments are **sticky**: calling this endpoint multiple times with the same session ID returns the same variant.
{% endhint %}

## Request

```
POST /api/v1/experiments/assign
```

**Headers:**

| Header          | Required | Value                        |
| --------------- | -------- | ---------------------------- |
| `Authorization` | Yes      | `Bearer <THREE_DEV_API_KEY>` |
| `Content-Type`  | Yes      | `application/json`           |

**Body:**

| Field        | Type   | Required | Description                                                                          |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------ |
| `session_id` | string | Yes      | The session identifier. Use the same ID you send in the `X-Three-Session-ID` header. |
| `use_case`   | string | Yes      | The use case slug.                                                                   |

**Example:**

```bash
curl -X POST https://api.three.dev/api/v1/experiments/assign \
  -H "Authorization: Bearer <THREE_DEV_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "78d7ee4c-c9f0-4515-9353-17283f3eb910",
    "use_case": "hotel-booking-assistant"
  }'
```

## Response

**When an experiment is running and a non-control variant is selected** (HTTP 200):

```json
{
  "experiment_id": "01926a3b-4c5d-7e8f-9a0b-1c2d3e4f5a6b",
  "variant_slug": "gpt-4.1",
  "metadata": {
    "model": "gpt-4.1"
  }
}
```

| Field           | Type   | Description                                                              |
| --------------- | ------ | ------------------------------------------------------------------------ |
| `experiment_id` | string | The UUID of the active experiment.                                       |
| `variant_slug`  | string | The slug of the variant the session was assigned to.                     |
| `metadata`      | object | The variant's metadata JSON, as configured when creating the experiment. |

**When no experiment is running or control is selected** (HTTP 200):

```json
null
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.three.dev/api-reference/assign-session.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.