# Groups

Canonical HTML: https://anchorshell.com/docs/groups

Create ordered regular Groups or request-aware Smart Groups, arrange models, and call either through the model field.

Last updated: 2026-09-17

A **Group** gives several models one request name. A regular Group contains models you choose, ranked in the order you want Relay to consider them. Relay waits for the preferred model when it can become available within the configured wait budget; with fallback enabled, it considers lower-ranked alternatives when that wait is too long.

A **Smart Group** chooses an approved model order based on the request. Use one when coding, writing, or other requests should select different models automatically. Smart Groups are hosted functionality; ordinary Groups and fallback remain available when self-hosting.

## Dashboard

### Regular Groups

1. Open **Groups → Add Group**. Enter a name and cooldown maximum wait, then create it.
2. Open **Edit group**. Drag models from **Available models** into the ranked list.
3. Drag assigned models to reorder them, or move one back to remove it. Membership/order changes save as you make them.
4. Adjust the group's name, enabled state, or wait setting and save those settings.

The current editor saves fallback enabled. The API also exposes the stored `allow_fallback` setting. Add upstream models through [Providers](https://anchorshell.com/docs/providers) first.

### Smart Groups

1. Choose **Add Smart Group**, enter a name, and create it.
2. Open its editor. Review the automatically prepared assignments: one primary model and up to two fallbacks for each intent.
3. Adjust assignments, the default routing list, confidence threshold, and cooldown maximum wait; choose **Save Smart Group**.

Low-confidence requests use the default list. The selected list still obeys access, limits, and availability. Copy the displayed call name, such as `smart/support`; Smart Groups support generation requests, not embeddings.

## API

Use a key with the relevant permissions; see [API authentication](https://anchorshell.com/docs/api). Replace placeholders with IDs from the corresponding list or create response.

Use `relay:groups:read` for reads and `relay:groups:manage` for writes.

The existing management API still calls regular Groups `routing-lanes` and their model assignments `lane-memberships`. These names configure saved Groups; **they are never inference parameters**. A cleaner public naming API is not yet available.

### List Groups

```bash
curl 'https://api.anchorshell.com/api/relay/routing-lanes' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
[
  {
    "id": "<GROUP_ID>",
    "name": "agentic",
    "slug": "agentic",
    "default_max_wait_ms": 60000,
    "allow_fallback": true,
    "enabled": true
  }
]
```

To retrieve one Group, find its `id` in this response. A single-Group GET endpoint is not implemented.

### Create a Group

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/routing-lanes' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "agentic",
  "default_max_wait_ms": 60000,
  "allow_fallback": true,
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<GROUP_ID>",
  "name": "agentic",
  "slug": "agentic",
  "default_max_wait_ms": 60000,
  "allow_fallback": true,
  "enabled": true
}
```

### Update a Group

```bash
curl -X PUT 'https://api.anchorshell.com/api/relay/routing-lanes/<GROUP_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "agentic",
  "default_max_wait_ms": 30000,
  "allow_fallback": true,
  "enabled": true
}'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<GROUP_ID>",
  "name": "agentic",
  "slug": "agentic",
  "default_max_wait_ms": 30000,
  "allow_fallback": true,
  "enabled": true
}
```

### List model assignments

```bash
curl 'https://api.anchorshell.com/api/relay/lane-memberships' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
[
  {
    "id": "<MEMBERSHIP_ID>",
    "lane_id": "<GROUP_ID>",
    "endpoint_id": "<MODEL_ID>",
    "manual_rank": 1,
    "enabled": true
  }
]
```

Find assignments whose `lane_id` equals the Group ID. Each assignment has its own `id`.

### Add a model

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/lane-memberships' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "lane_id": "<GROUP_ID>",
  "endpoint_id": "<MODEL_ID>",
  "manual_rank": 1,
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<MEMBERSHIP_ID>",
  "lane_id": "<GROUP_ID>",
  "endpoint_id": "<MODEL_ID>",
  "manual_rank": 1,
  "enabled": true
}
```

### Reorder a model

```bash
curl -X PUT 'https://api.anchorshell.com/api/relay/lane-memberships/<MEMBERSHIP_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "manual_rank": 2,
  "enabled": true
}'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<MEMBERSHIP_ID>",
  "lane_id": "<GROUP_ID>",
  "endpoint_id": "<MODEL_ID>",
  "manual_rank": 2,
  "enabled": true
}
```

Update each affected assignment's `manual_rank` to give the list distinct ranks. The API has no atomic whole-list reorder operation.

### Remove a model

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/lane-memberships/<MEMBERSHIP_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

### Delete a Group

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/routing-lanes/<GROUP_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

Deleting a Group removes its memberships, not the provider models.

### Call a Group

```bash
curl -X POST 'https://api.anchorshell.com/v1/chat/completions' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "agentic",
  "messages": [
    {
      "role": "user",
      "content": "Explain why queue-first routing preserves better models."
    }
  ]
}'
```

**Response — 200 OK**

Example non-streaming response (selected fields). Content, model, and usage depend on the selected provider.

```json
{
  "id": "<COMPLETION_ID>",
  "object": "chat.completion",
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Relay waits for the preferred model before considering fallback."
      },
      "finish_reason": "stop"
    }
  ]
}
```

Use the Smart Group call name in the same `model` field when applicable.

## Next

[Guardrails](https://anchorshell.com/docs/guardrails).