Set Group Assignment

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))

{
  "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"
          }
        ]
      }
    ]
  }
}

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.

Authentication

AuthorizationBearer

A write key, issued by Captain. Server side only. Sent as Authorization: Bearer <key>.

Path parameters

indexstringRequiredformat: "^[a-z0-9][a-z0-9_-]{0,47}$"

index name

Request

This endpoint expects an object.

assignmentobjectOptional

or no layers: no routing

Response headers

X-Captain-Applied-Seqinteger

the last update seq search had applied when this request started; the answer reflects at least that much (GET …/updates applied_seq). Not on 401 or 403, nor for an index this server does not have

X-Captain-Index-IncarnationstringOptional

the index’s incarnation, an opaque string: it changes only when the index is deleted and created again (whose seqs start again at 1), or restored from a backup (whose seqs continue from the backup’s). Sent with X-Captain-Applied-Seq

Response

saved

indexstringOptional