# Custom attributes (v1)

> List, create, and update the custom attribute definitions for an agent: GET/POST /api/v1/chatbots/:chatbotId/custom-attributes and PUT /:name.

Custom attributes define the extra fields you can store on contacts (for example `plan` or `ltv`). These endpoints manage the **definitions**; the values live on each contact's `custom_attributes` object. All paths are authenticated with `Authorization: Bearer oc_...` and `chatbotId` is your agent id.

## GET /api/v1/chatbots/:chatbotId/custom-attributes

List the attribute definitions for an agent.

```bash
curl https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes \
  -H "Authorization: Bearer $BOOKBAG_API_KEY"
```

## POST /api/v1/chatbots/:chatbotId/custom-attributes

Create an attribute definition.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| name | string | Yes | Must start with a letter; letters, numbers, underscores, hyphens only. Unique per agent. |
| label | string | No | Display label. Defaults to `name`. |
| type | string | No | One of `text`, `number`, `boolean`, `date`. Defaults to `text`. |
| description | string | No | Free-text help. |
| archived | boolean | No | Create it archived (hidden from the contact UI). |

```bash
curl https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ltv", "label": "Lifetime value", "type": "number" }'
```

## PUT /api/v1/chatbots/:chatbotId/custom-attributes/:name

Update an attribute definition by `name`. You can change `label`, `description`, and `archived`. The `name` and `type` are fixed once created.

| Field | In | Type | Notes |
| --- | --- | --- | --- |
| name | path | string | The attribute name. |
| label | body | string | New display label. |
| description | body | string | New description. |
| archived | body | boolean | Archive or unarchive. |

```bash
curl -X PUT https://app.bookbag.ai/api/v1/chatbots/123/custom-attributes/ltv \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "LTV (USD)", "archived": true }'
```

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | Success. |
| 400 | Invalid `name` or `type`. Body: `{ message }` describing the rule. |
| 401 | Missing or invalid key. |
| 404 | Unknown chatbot/attribute. Body: `{ message: "Resource not found" }`. |
| 409 | An attribute with that name already exists. Body: `{ message: "Attribute already exists" }`. |

See [Errors](/docs/api/errors).