> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Set Group Assignment

PUT https://acme.captain.dev/v1/indexes/{index}/assignment
Content-Type: application/json

Split this index's shoppers between copies of it, for a pilot or an A/B test. A search that sends a `user_token` runs on that shopper's group: the same shopper always lands in the same group. A search without one runs on this index as before. Searches and their analytics stay under this index, so Get Revenue can compare the groups. Applies to the next search, with no rebuild. `{}` clears it.

Reference: https://docs.captain.dev/reference/product-search/indexes/set-group-assignment

## Authentication

- `Authorization` header (bearer token, required) — A write key, issued by Captain. Server side only. Sent as Authorization: Bearer \<key>.

## Request

### Path parameters

- `index` (string, required) — index name

### Headers

- `Idempotency-Key` (string, optional) — Replays within 24 hours return the stored response (header Idempotent-Replayed: true). The same key on a different request answers 422. A concurrent duplicate answers 409. Failed requests do not keep the key.

### Body (application/json)

This endpoint expects an object.

- `assignment` (Assignment, optional) — &#x20;or no layers: no routing

## Response

### 200

saved

- `index` (string, optional)
- `assignment` (Assignment, optional) — &#x20;or no layers: no routing

## Types

### Assignment

&#x20;or no layers: no routing

- `layers` (list of AssignmentLayersItems, optional)

### AssignmentLayersItems

- `id` (string, required)
- `salt` (string, required)
- `groups` (list of AssignmentLayersItemsGroupsItems, required) — shares in (0, 1], summing to 1

### AssignmentLayersItemsGroupsItems

- `name` (string, required)
- `share` (double, required)
- `index` (string, optional, nullable) — a copy that serves this group; null: the catalog itself (the next layer is tried)

## Examples

**Request**

```json
{
  "assignment": {
    "layers": [
      {
        "id": "ranking-test",
        "salt": "2026-10-ranking",
        "groups": [
          {
            "name": "control",
            "share": 0.5,
            "index": null
          },
          {
            "name": "new-ranking",
            "share": 0.5,
            "index": "products-new-ranking"
          }
        ]
      }
    ]
  }
}
```

**Response**

```json
{
  "index": "products",
  "assignment": {
    "layers": [
      {
        "id": "ranking-test",
        "salt": "2026-10-ranking",
        "groups": [
          {
            "name": "control",
            "share": 0.5,
            "index": null
          },
          {
            "name": "new-ranking",
            "share": 0.5,
            "index": "products-new-ranking"
          }
        ]
      }
    ]
  }
}
```

**SDK Code**

```python Python REST
import json
import requests
import uuid

BASE_URL = "https://acme.captain.dev"
API_KEY = "your_write_key"
INDEX = "products"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}

response = requests.put(
    f"{BASE_URL}/v1/indexes/{INDEX}/assignment",
    headers=headers,
    json={
        "assignment": {
            "layers": [
                {
                    "id": "ranking-test",
                    "salt": "2026-10-ranking",
                    "groups": [
                        {"name": "control", "share": 0.5, "index": None},
                        {
                            "name": "new-ranking",
                            "share": 0.5,
                            "index": "products-new-ranking",
                        },
                    ],
                },
            ],
        },
    },
    timeout=30.0,
)

print(json.dumps(response.json(), indent=2))
```

```typescript TypeScript REST
const BASE_URL = "https://acme.captain.dev";
const API_KEY = "your_write_key";
const index = "products";

const response = await fetch(`${BASE_URL}/v1/indexes/${index}/assignment`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    assignment: {
      layers: [
        {
          id: "ranking-test",
          salt: "2026-10-ranking",
          groups: [
            { name: "control", share: 0.5, index: null },
            { name: "new-ranking", share: 0.5, index: "products-new-ranking" },
          ],
        },
      ],
    },
  }),
});

const result = await response.json();
console.log(JSON.stringify(result, null, 2));
```