# API: scripts, steps and folders

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

A **script** is a fixed sequence of steps for one creator: each step is a text, optional media from the Vault, a price in Stars and a wait before the next one. Scripts sit in folders. One script per creator can be marked **first**: it runs on new conversations.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/scripts` | List scripts (`creator_id=` required, `folder_id=`, `active=true`) | `can_setup` | Planned |
| POST | `/scripts` | Create a script with its steps | `can_setup` | Planned |
| GET | `/scripts/{id}` | One script and its steps | `can_setup` | Planned |
| PUT | `/scripts/{id}` | Replace a script (name, steps, folder, accounts) | `can_setup` | Planned |
| PATCH | `/scripts/{id}` | Turn it on or off, mark it first, move it to a folder | `can_setup` | Planned |
| POST | `/scripts/{id}/duplicate` | Copy a script (the copy is never first) | `can_setup` | Planned |
| DELETE | `/scripts/{id}` | Delete a script | `can_setup` | Planned |
| GET | `/scripts/folders` | Folders of a creator (`creator_id=`) | `can_setup` | Planned |
| POST | `/scripts/folders` | Create a folder | `can_setup` | Planned |
| PATCH | `/scripts/folders/{id}` | Rename a folder | `can_setup` | Planned |
| DELETE | `/scripts/folders/{id}` | Delete a folder; its scripts move to "No folder" | `can_setup` | Planned |
| POST | `/conversations/{id}/script` | Run a script on one conversation (see [Conversations](https://lanachat.ai/guides/api-conversations/)) | `can_chat` | Planned |

## The script object

```json
{
  "id": "scr_204",
  "creator_id": "cr_lea",
  "name": "Welcome message",
  "goal": "First sale within the first day",
  "folder_id": "fld_12",
  "active": true,
  "first": true,
  "account_ids": null,
  "steps": [
    { "id": "st_1", "name": "Hello", "text": "Hey you 😊 glad you found me here", "media": [], "wait_minutes": 0, "pricing": { "mode": "free" } },
    { "id": "st_2", "name": "First set", "text": "Made this one this morning…", "media": ["med_5521", "med_5522"], "wait_minutes": 20, "pricing": { "mode": "paid", "stars": 250, "discount_stars": 200 } }
  ],
  "created_at": "2026-09-30T10:00:00Z",
  "updated_at": "2026-10-05T16:22:00Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Starts with `scr_` |
| `creator_id` | string | The creator whose fans receive it |
| `name` | string | Its name in the Console |
| `goal` | string or null | What the script is for, in your words |
| `folder_id` | string or null | Its folder; `null` is "No folder" |
| `active` | boolean | `false` means it never runs |
| `first` | boolean | `true` means it runs on new conversations |
| `account_ids` | array or null | `null` means every Telegram account of the creator; an array means only those (at least one) |
| `steps` | array | The steps, in order (see below) |
| `created_at`, `updated_at` | string | ISO 8601, UTC |

Each step has:

| Field | Type | Description |
|---|---|---|
| `id` | string | Starts with `st_` |
| `name` | string | Its name in the editor |
| `text` | string | The message the fan receives |
| `media` | array of strings | Media ids from the creator's [Vault](https://lanachat.ai/guides/api-vault/) |
| `wait_minutes` | number | Wait before this step is sent |
| `pricing.mode` | string | `free`, `vault` (each media at its Vault price) or `paid` (one price for the whole step) |
| `pricing.stars` | number | The price in Stars, when `mode` is `paid` |
| `pricing.discount_stars` | number | Optional lower price in Stars |

Setting `first: true` on a script removes it from the creator's other scripts.

## Scripts

### List scripts

`GET /scripts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Yes | The creator |
| `folder_id` | string | No | Only the scripts of this folder |
| `active` | boolean | No | `true` lists only the scripts that are on |
| `limit`, `cursor` | number, string | No | [Pagination](https://lanachat.ai/guides/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/scripts?creator_id=cr_lea&active=true" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

The answer is a page of script objects in `data`, with `next_cursor`. Without `creator_id` the API answers `400`.

### Create a script

`POST /scripts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Yes | The creator |
| `name` | string | Yes | Its name |
| `steps` | array | Yes | The steps, as in the object above (without `id`) |
| `goal` | string | No | What it is for |
| `folder_id` | string | No | A folder of the same creator |
| `account_ids` | array of strings | No | Only these accounts; leave it out for all |

```bash
curl -X POST https://api.lanachat.ai/v1/scripts \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Win back", "steps": [{"name": "Miss you", "text": "Hey stranger, where did you go?", "wait_minutes": 0, "pricing": {"mode": "free"}}]}'
```

```json
{
  "id": "scr_231",
  "creator_id": "cr_lea",
  "name": "Win back",
  "goal": null,
  "folder_id": null,
  "active": true,
  "first": false,
  "account_ids": null,
  "steps": [ { "id": "st_1", "name": "Miss you", "text": "Hey stranger, where did you go?", "media": [], "wait_minutes": 0, "pricing": { "mode": "free" } } ],
  "created_at": "2026-10-06T14:30:00Z",
  "updated_at": "2026-10-06T14:30:00Z"
}
```

The answer is the new script (`201`), active, not first, in no folder. A media id from another creator's Vault is refused (`400`).

### Get a script

`GET /scripts/{id}` · `can_setup`

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

The answer is the script object with all its steps.

### Replace a script

`PUT /scripts/{id}` · `can_setup`

Send the whole script: `name`, `steps`, `folder_id` and `account_ids`, as in Create a script. Steps you leave out are removed.

```bash
curl -X PUT https://api.lanachat.ai/v1/scripts/scr_231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Win back", "folder_id": "fld_12", "account_ids": null, "steps": [{"name": "Miss you", "text": "Hey stranger, where did you go?", "wait_minutes": 0, "pricing": {"mode": "free"}}, {"name": "Gift", "text": "Kept this one for you", "media": ["med_5522"], "wait_minutes": 30, "pricing": {"mode": "paid", "stars": 200}}]}'
```

The answer is the updated script. An empty `account_ids` array answers `400`: use `null` for every account.

### Turn on, mark first, move

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `active` | boolean | No | Turn it on or off |
| `first` | boolean | No | `true` makes it the script of new conversations |
| `folder_id` | string or null | No | Move it; `null` is "No folder" |

```bash
curl -X PATCH https://api.lanachat.ai/v1/scripts/scr_231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first": true}'
```

The answer is the updated script. The creator's previous first script loses `first`.

### Duplicate a script

`POST /scripts/{id}/duplicate` · `can_setup`

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

The answer is the copy (`201`). The copy is never first.

### Delete a script

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

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

## Folders

### List folders

`GET /scripts/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Yes | The creator |

```bash
curl "https://api.lanachat.ai/v1/scripts/folders?creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

### Create a folder

`POST /scripts/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Yes | The creator |
| `name` | string | Yes | Folder name |

```bash
curl -X POST https://api.lanachat.ai/v1/scripts/folders \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Win back"}'
```

### Rename a folder

`PATCH /scripts/folders/{id}` · `can_setup`

```bash
curl -X PATCH https://api.lanachat.ai/v1/scripts/folders/fld_12 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Welcome"}'
```

### Delete a folder

`DELETE /scripts/folders/{id}` · `can_setup`

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

Its scripts are kept and move to "No folder".

## Run a script on a conversation

`POST /conversations/{id}/script` · `can_chat`

Starts a script on one fan's conversation: `state` becomes `script` until it ends. Body, example and rules are in [Conversations](https://lanachat.ai/guides/api-conversations/).

## Related

- [LanaChat API: quick start, authentication and errors](https://lanachat.ai/guides/api-overview/)
- [Scripts: write, organize and use them](https://lanachat.ai/guides/scripts/)
- [Scripts vs. AI: when the bot follows a script](https://lanachat.ai/guides/scripts-vs-ai/)