API reference

Creators API

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.

Planned

Every endpoint on this page is marked Planned: it is the published contract the backend is built from, and it does not answer yet.

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 progress (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	Setup progress: steps `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/creatorsPlannedNeeds 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

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

const res = await fetch('https://api.lanachat.ai/v1/creators?status=active,paused', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/creators?status=active,paused",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

{
  "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/creatorsPlannedNeeds can_setup

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

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"}'

const res = await fetch('https://api.lanachat.ai/v1/creators', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Lea', timezone: 'Europe/Paris' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/creators",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"name": "Lea", "timezone": "Europe/Paris"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

{
  "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. A missing name answers 400.

Get a creator #

GET/creators/{id}PlannedNeeds can_setup or can_fan_read

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/creators/cr_lea",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

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

Update a creator #

PATCH/creators/{id}PlannedNeeds 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

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"}'

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ timezone: 'Europe/Madrid', brain_id: 'br_lea_main' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.patch(
    "https://api.lanachat.ai/v1/creators/cr_lea",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    json={"timezone": "Europe/Madrid", "brain_id": "br_lea_main"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

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

Pause and resume #

POST/creators/{id}/pausePlannedPOST/creators/{id}/resumePlannedNeeds can_setup

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/pause', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/creators/cr_lea/pause",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

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}PlannedNeeds can_setup

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.delete(
    "https://api.lanachat.ai/v1/creators/cr_lea",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

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}/identityPlannedNeeds can_setup

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/identity', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/creators/cr_lea/identity",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The answer has the same fields as the identity below.

Replace the identity #

PUT/creators/{id}/identityPlannedNeeds 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"]`

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"]}'

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/identity', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Lea',
    nicknames: ['Lele'],
    date_of_birth: '2001-04-12',
    nationality: 'FR',
    languages: ['fr', 'en'],
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.put(
    "https://api.lanachat.ai/v1/creators/cr_lea/identity",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    json={
        "first_name": "Lea",
        "nicknames": ["Lele"],
        "date_of_birth": "2001-04-12",
        "nationality": "FR",
        "languages": ["fr", "en"],
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

{
  "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}/personaPlannedNeeds can_engine

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/persona', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/creators/cr_lea/persona",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

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

Change persona pages #

PATCH/creators/{id}/personaPlannedNeeds 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

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"}]}}'

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/persona', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    voice: {
      style: 'Short, warm, a few emojis, never formal.',
      phrase_bank: [{ trigger: 'Are you a bot?', reply: 'Haha no, just slow at typing' }],
    },
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.patch(
    "https://api.lanachat.ai/v1/creators/cr_lea/persona",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    json={
        "voice": {
            "style": "Short, warm, a few emojis, never formal.",
            "phrase_bank": [{"trigger": "Are you a bot?", "reply": "Haha no, just slow at typing"}],
        },
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

{
  "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 before peak time.

Setup progress #

Get the setup progress #

GET/creators/{id}/setupPlannedNeeds can_setup

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

const res = await fetch('https://api.lanachat.ai/v1/creators/cr_lea/setup', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/creators/cr_lea/setup",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

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

Errors #

Every endpoint answers errors in the same JSON body, {"error": {"code": "…", "message": "…"}}, with the common codes 400, 401, 402, 403, 404, 409, 429 and 500 listed in Errors. What the endpoints of this page say they answer:

Endpoint	Status	When
Create a creator	`400`	A missing `name` answers `400`.
Get a creator	`404`	An unknown id answers `404`.
Update a creator	`404`	A `brain_id` of another workspace answers `404`.
Replace the identity	`400`	A creator under 18 is refused (`400`).

Tutorial: API: creators, identity and persona