# API: creators, identity and persona

_API · 6 min read · Updated 2026-10-22 · https://lanachat.ai/guides/api-creators/_

A **creator** is a person your agency runs on Telegram. She has an **identity** (who she is), a **persona** (how she talks, in eight pages) and links to her Telegram accounts, her AI Brain, her Vault and her scripts. These endpoints match the **Creators** page of the Console.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/creators` | List creators (`status=active,paused,archived`, `q=` name search) | `can_setup` or `can_fan_read` | Planned |
| POST | `/creators` | Create a creator (name required) | `can_setup` | Planned |
| GET | `/creators/{id}` | One creator with her setup progress | `can_setup` or `can_fan_read` | Planned |
| PATCH | `/creators/{id}` | Rename, change her photo, time zone or linked brain | `can_setup` | Planned |
| POST | `/creators/{id}/pause` | Pause her: the AI stops answering on all her accounts | `can_setup` | Planned |
| POST | `/creators/{id}/resume` | Resume a paused creator | `can_setup` | Planned |
| DELETE | `/creators/{id}` | Archive her (her fans and sales are kept) | `can_setup` | Planned |
| GET | `/creators/{id}/identity` | Her identity card | `can_setup` | Planned |
| PUT | `/creators/{id}/identity` | Replace her identity card | `can_setup` | Planned |
| GET | `/creators/{id}/persona` | The eight persona pages and how complete they are | `can_engine` | Planned |
| PATCH | `/creators/{id}/persona` | Change one or more persona pages | `can_engine` | Planned |
| GET | `/creators/{id}/setup` | The Setup card: each step and whether it is done | `can_setup` | Planned |

## The creator object

```json
{
  "id": "cr_lea",
  "name": "Lea",
  "status": "active",
  "photo_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/photo.jpg",
  "timezone": "Europe/Paris",
  "brain_id": "br_lea_main",
  "accounts": { "total": 3, "connected": 2 },
  "setup": { "done": 5, "total": 7 },
  "created_at": "2026-08-14T09:12:00Z",
  "updated_at": "2026-10-05T18:40:11Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Starts with `cr_` |
| `name` | string | Her name in the Console |
| `status` | string | `active`, `paused` or `archived` |
| `photo_url` | string or null | Her photo |
| `timezone` | string | IANA time zone, for example `Europe/Paris` |
| `brain_id` | string or null | The AI Brain linked to her |
| `accounts` | object | Counts of her Telegram accounts: `total`, `connected` |
| `setup` | object | Steps of the Setup card `done` out of `total` |
| `created_at`, `updated_at` | string | ISO 8601, UTC |

A paused creator keeps her accounts connected but the AI does not answer; scripts already running stop at their next step.

## Creators

### List creators

`GET /creators` · `can_setup` or `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `active`, `paused` or `archived`; several separated by commas |
| `q` | string | No | Part of her name |
| `limit`, `cursor` | number, string | No | [Pagination](https://lanachat.ai/guides/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/creators?status=active,paused" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "cr_lea", "name": "Lea", "status": "active", "photo_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/photo.jpg", "timezone": "Europe/Paris", "brain_id": "br_lea_main", "accounts": { "total": 3, "connected": 2 }, "setup": { "done": 5, "total": 7 }, "created_at": "2026-08-14T09:12:00Z", "updated_at": "2026-10-05T18:40:11Z" },
    { "id": "cr_mia", "name": "Mia", "status": "paused", "photo_url": null, "timezone": "Europe/Rome", "brain_id": "br_mia_main", "accounts": { "total": 2, "connected": 2 }, "setup": { "done": 7, "total": 7 }, "created_at": "2026-07-02T11:00:00Z", "updated_at": "2026-10-01T08:15:00Z" }
  ],
  "next_cursor": null
}
```

### Create a creator

`POST /creators` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Her name in the Console |
| `timezone` | string | No | IANA time zone |

```bash
curl -X POST https://api.lanachat.ai/v1/creators \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lea", "timezone": "Europe/Paris"}'
```

```json
{
  "id": "cr_lea",
  "name": "Lea",
  "status": "active",
  "photo_url": null,
  "timezone": "Europe/Paris",
  "brain_id": null,
  "accounts": { "total": 0, "connected": 0 },
  "setup": { "done": 0, "total": 7 },
  "created_at": "2026-10-06T14:00:00Z",
  "updated_at": "2026-10-06T14:00:00Z"
}
```

The answer is the new creator (`201`). She starts with an empty identity and persona, no account and no brain: the `setup` counter shows what is left, like the Setup card in the Console. A missing `name` answers `400`.

### Get a creator

`GET /creators/{id}` · `can_setup` or `can_fan_read`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer is the creator object. An unknown id answers `404`.

### Update a creator

`PATCH /creators/{id}` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | New name |
| `timezone` | string | No | IANA time zone |
| `brain_id` | string or null | No | The brain to link; `null` unlinks it |

```bash
curl -X PATCH https://api.lanachat.ai/v1/creators/cr_lea \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "Europe/Madrid", "brain_id": "br_lea_main"}'
```

The answer is the updated creator. A `brain_id` of another workspace answers `404`.

### Pause and resume

`POST /creators/{id}/pause` and `POST /creators/{id}/resume` · `can_setup`

```bash
curl -X POST https://api.lanachat.ai/v1/creators/cr_lea/pause \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Pausing stops the AI on all her accounts at once; `resume` turns it back on. Both answer the creator object with its new status.

### Archive a creator

`DELETE /creators/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/creators/cr_lea \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer is the creator with `status: "archived"`. Her fans and sales are kept and still count in your stats.

## Identity

### Get the identity

`GET /creators/{id}/identity` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/identity \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer has the same fields as the identity below.

### Replace the identity

`PUT /creators/{id}/identity` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | No | Her first name, as fans know it |
| `nicknames` | array of strings | No | Short names she answers to |
| `date_of_birth` | string | No | `YYYY-MM-DD`; she must be 18 or older |
| `nationality` | string | No | Two-letter country code, for example `FR` |
| `languages` | array of strings | No | Languages she speaks, for example `["fr", "en"]` |

```bash
curl -X PUT https://api.lanachat.ai/v1/creators/cr_lea/identity \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Lea", "nicknames": ["Lele"], "date_of_birth": "2001-04-12", "nationality": "FR", "languages": ["fr", "en"]}'
```

```json
{
  "first_name": "Lea",
  "nicknames": ["Lele"],
  "date_of_birth": "2001-04-12",
  "zodiac_sign": "aries",
  "nationality": "FR",
  "languages": ["fr", "en"]
}
```

`zodiac_sign` is computed from the date of birth. A creator under 18 is refused (`400`). `PUT` replaces the whole card: a field you leave out is emptied.

## Persona

The persona has the same eight pages as the Console: `appearance`, `life`, `voice`, `mimic`, `personality`, `memory`, `boundaries`, `examples`. Each page is an object of text fields; `PATCH` changes only the pages you send.

### Get the persona

`GET /creators/{id}/persona` · `can_engine`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/persona \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer has the same shape as below, with all eight pages.

### Change persona pages

`PATCH /creators/{id}/persona` · `can_engine`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `appearance`, `life`, `voice`, `mimic`, `personality`, `memory`, `boundaries`, `examples` | object | At least one | The pages to change; the others are kept |

```bash
curl -X PATCH https://api.lanachat.ai/v1/creators/cr_lea/persona \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"voice": {"style": "Short, warm, a few emojis, never formal.", "phrase_bank": [{"trigger": "Are you a bot?", "reply": "Haha no, just slow at typing"}]}}'
```

```json
{
  "complete_percent": 64,
  "pages": {
    "voice": { "style": "Short, warm, a few emojis, never formal.", "phrase_bank": [ { "trigger": "Are you a bot?", "reply": "Haha no, just slow at typing" } ], "complete": true },
    "mimic": { "enabled": false, "lines": [], "complete": false }
  },
  "reply_language": "fr"
}
```

> Tip: The persona feeds every brain linked to the creator. Change it in a quiet hour, then test the brain in the [Playground](https://lanachat.ai/guides/api-ai-brains/) before peak time.

## Setup progress

### Get the Setup card

`GET /creators/{id}/setup` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/creators/cr_lea/setup \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer lists each step of the Setup card of the Console and whether it is done. `setup` in the creator object is the same progress as a counter (`done` out of `total`).

## Related

- [LanaChat API: quick start, authentication and errors](https://lanachat.ai/guides/api-overview/)
- [Add a creator](https://lanachat.ai/guides/add-a-creator/)
- [Creator settings (persona, prices, language)](https://lanachat.ai/guides/creator-settings/)