Manage Labels - Aampe Docs

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.

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:

[
  {
    "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:

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

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

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.

Using Label IDs

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

1. Formula creation — declare which labels the formula uses

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

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

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},
])

⌘I