> ## Documentation Index
> Fetch the complete documentation index at: https://kb.aampe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Labels

> How to list, create, and use labels with the Composer API.

## List Existing Labels

Before creating new labels, fetch the ones that already exist. Labels rarely change — you can cache this list for the duration of a session.

```python theme={null}
import requests

BASE_URL = "https://composer.api.aampe.com/api"
headers  = {"X-API-KEY": "YOUR_API_KEY"}

response = requests.get(f"{BASE_URL}/labels", headers=headers)
response.raise_for_status()

labels = response.json()
for label in labels:
    if label["archived_at"] is None:  # skip archived labels
        print(f"[{label['variant_type']}] {label['id']}: {label['label_name']}")
```

**Response:**

```json theme={null}
[
  {
    "id": 101,
    "label_name": "Curiosity",
    "label_description": "Piques interest and invites exploration",
    "variant_type": "Offering",
    "archived_at": null
  },
  {
    "id": 102,
    "label_name": "Urgency",
    "label_description": "Creates time pressure",
    "variant_type": "Offering",
    "archived_at": null
  }
]
```

To look up labels by component type:

```python theme={null}
from collections import defaultdict

by_type = defaultdict(list)
for label in labels:
    if label["archived_at"] is None:
        by_type[label["variant_type"]].append(label)

# e.g. by_type["Offering"] → list of all Offering labels
```

***

## Create a Label

```
POST /labels
```

```python theme={null}
response = requests.post(
    f"{BASE_URL}/labels",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "label_name":        "Calm",
        "label_description": "Gentle, reassuring tone",
        "variant_type":      "Offering",
    },
)
response.raise_for_status()
label_id = response.json()["id"]
print(f"Created label: {label_id}")
```

| Field               | Type   | Required | Description                                                                                                        |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `label_name`        | string | Yes      | Human-readable name                                                                                                |
| `label_description` | string | No       | What this label means                                                                                              |
| `variant_type`      | string | Yes      | The component type `data_key` this label applies to — must match exactly (e.g. `"Offering"`, `"ValueProposition"`) |

<Note>
  Create one label per semantic concept per component type. If you need a `"Calm"` label for both Offering and ValueProposition variants, create two separate labels — one with each `variant_type`.
</Note>

***

## Using Label IDs

Once you have label IDs, they appear in three places:

### 1. Formula creation — declare which labels the formula uses

```python theme={null}
requests.post(f"{BASE_URL}/formulas", headers=headers, json={
    "name": "My Formula",
    "message_type": "push",
    "structure": [],
    "labels": [
        {"label_id": 101, "variant_type": "Offering",         "component_type_id": CT_OFFERING},
        {"label_id": 102, "variant_type": "Offering",         "component_type_id": CT_OFFERING},
        {"label_id": 103, "variant_type": "ValueProposition", "component_type_id": CT_VALUE_PROPOSITION},
    ],
})
```

### 2. Structure definition — label the seed variant

```python theme={null}
{
    "id":          component_instance_id,
    "kind":        "variant",
    "variantType": "Offering",
    "componentId": CT_OFFERING,
    "labelId":     101,                    # ← label for this seed variant
    "children":    [{"text": "Your copy here"}],
}
```

### 3. Variant creation — label each alternate

```python theme={null}
requests.post(f"{BASE_URL}/variants/create/bulk", headers=headers, json=[
    {"component_id": component_instance_id, "content": "Your copy",       "label_id": 101},
    {"component_id": component_instance_id, "content": "More urgent copy", "label_id": 102},
])
```