# Lists and fields The methods on this page work with a list's schema — its name and fields. How fields work and which types they have is described on the [Lists](https://support.watbot.org/api/lists#field-types) page. ## getListSchemas Returns the lists of all projects owned by the key holder, 50 per page. ```endpoint GET POST https://watbot.org/api/v1/getListSchemas ``` | Parameter | Type | Required | Description | |---|---|---|---| | `page` | integer | no | Page number, `1` by default | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/getListSchemas" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"page": 1}' ``` ```json title="Response 200" { "data": [ { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "title": { "name": "Title", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "price": { "name": "Price", "type": "money", "currency": "USD", "is_required": true, "is_hidden": false, "is_encryptable": false } }, "name": "Coffee shop menu", "bot_id": 12345, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-01T09:15:00+00:00", "updated_at": "2026-10-02T11:40:12+00:00" } ], "links": { "first": "…/v1/getListSchemas?page=1", "last": "…/v1/getListSchemas?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "…/v1/getListSchemas", "per_page": 50, "to": 1, "total": 1 } } ``` List fields in the response: | Field | Description | |---|---| | `id` | List ID | | `fields` | Fields: the key is the `slug`, the value holds the name (`name`), the type (`type`) and the settings. A money field also has `currency`. Fields created in your account may have other keys too | | `name` | List name | | `bot_id` | The bot the list was created in; `null` if the list was created in the project | | `project` | UUID of the project that owns the list | | `is_menu` | An outdated flag; it does not affect how the list works | | `created_at`, `updated_at` | When the list was created and last changed | Notes: - The page size is 50 lists and cannot be changed. The total number of pages is in `meta.last_page`, the address of the next page is in `links.next`. - Lists of projects you were invited to as a team member are not included: the API only works with the projects of the key holder. ## getListSchema Returns one list with its fields. ```endpoint GET POST https://watbot.org/api/v1/getListSchema ``` | Parameter | Type | Required | Description | |---|---|---|---| | `schema_id` | string | yes | List ID | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/getListSchema" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}' ``` ```json title="Response 200" { "data": { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "title": { "name": "Title", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "price": { "name": "Price", "type": "money", "currency": "USD", "is_required": true, "is_hidden": false, "is_encryptable": false } }, "name": "Coffee shop menu", "bot_id": 12345, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-01T09:15:00+00:00", "updated_at": "2026-10-02T11:40:12+00:00" } } ``` ```json title="Response 404" { "message": "Schema not found", "error": "Schema not found", "errors": { "schema_id": ["Schema not found"] } } ``` Errors: - The list does not exist or has been deleted — `404`. The error text is in `error` and `message`; for compatibility it is also in `errors.schema_id`. - The list belongs to someone else's project — `403`. ## createListSchema Creates a list with fields — in a project or in a bot. ```endpoint GET POST https://watbot.org/api/v1/createListSchema ``` | Parameter | Type | Required | Description | |---|---|---|---| | `name` | string | yes | List name, up to 255 characters | | `project_uuid` | string | yes, if there is no `bot_id` | UUID of the project to create the list in | | `bot_id` | integer | yes, if there is no `project_uuid` | Bot ID: the list goes to this bot's project and is marked as created in it. If both parameters are sent, `bot_id` is used | | `fields` | array | yes | List fields — from 1 to 30 | | `fields[].name` | string | yes | Field name, up to 255 characters | | `fields[].slug` | string | yes | Field slug: letters, digits, `-` and `_`, up to 255 characters; Latin letters are best. Must be unique within the list and must not match the [service names](https://support.watbot.org/api/lists#limits) | | `fields[].type` | string | yes | Field type: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot` | | `fields[].currency` | string | no | Only for `money`: a three-letter ISO 4217 currency code — `USD`, `EUR`, `GBP`. `USD` by default. An unknown code — `422` | | `fields[].is_required` | boolean | no | Required field. `true` by default | | `fields[].is_hidden` | boolean | no | Hide the field from the interface. `false` by default | | `fields[].is_encryptable` | boolean | no | Store the value encrypted. `false` by default | | `is_menu` | boolean | no | An outdated flag; it does not affect how the list works | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/createListSchema" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "project_uuid": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "name": "Coffee shop menu", "fields": [ {"name": "Title", "slug": "title", "type": "string"}, {"name": "Price", "slug": "price", "type": "money", "currency": "USD"}, {"name": "Photo", "slug": "photo", "type": "image", "is_required": false}, {"name": "In stock", "slug": "in_stock", "type": "bool", "is_required": false} ] }' ``` ```json title="Response 201" { "data": { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "title": { "name": "Title", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "price": { "name": "Price", "type": "money", "is_required": true, "is_hidden": false, "is_encryptable": false, "currency": "USD" }, "photo": { "name": "Photo", "type": "image", "is_required": false, "is_hidden": false, "is_encryptable": false }, "in_stock": { "name": "In stock", "type": "bool", "is_required": false, "is_hidden": false, "is_encryptable": false } }, "name": "Coffee shop menu", "bot_id": null, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-03T08:00:00+00:00", "updated_at": "2026-10-03T08:00:00+00:00" } } ``` ```json title="Response 422" { "message": "The slug is reserved.", "errors": { "fields.0.slug": ["The slug is reserved."] } } ``` Notes and errors: - Fields are added to the list in the order they are sent. - You can create a list only in your own project or your own bot. A bot or project of another account, including one you were invited to as a team member, — `403`. - A `bot_id` or `project_uuid` that does not exist — `422`. - A repeated `slug` — `422` with an error on the `fields.N.slug` field, where N is the zero-based position of the field in the array. - An unknown currency code — `422` with an error on the `fields.N.currency` field. - The project already has 5000 lists — `403`: `{"message": "A project cannot have more than 5000 lists", "error": "A project cannot have more than 5000 lists"}`. - In a `GET` request, fields are passed in the address like this: `fields[0][name]=Title&fields[0][slug]=title&fields[0][type]=string`. Sending `POST` with JSON is easier. ## deleteListSchema Deletes a list together with its records. ```endpoint GET POST https://watbot.org/api/v1/deleteListSchema ``` | Parameter | Type | Required | Description | |---|---|---|---| | `schema_id` | string | yes | List ID | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/deleteListSchema" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}' ``` ```json title="Response 404" { "message": "Schema not found", "error": "Schema not found", "errors": { "schema_id": ["Schema not found"] } } ``` A successful response is code `204` with no body. Notes and errors: - Before deleting, make sure the list is not selected in any bot blocks: after deletion the blocks will not find records. - After deletion, the list's records are found neither by `getListItems` nor by `item_id`: `updateListItem` and `deleteListItem` respond with `404`. - The list does not exist or has already been deleted — `404`, as in [`getListSchema`](#getlistschema). - The list belongs to someone else's project — `403`. ## addListSchemaField Adds a field to the end of the list. ```endpoint GET POST https://watbot.org/api/v1/addListSchemaField ``` | Parameter | Type | Required | Description | |---|---|---|---| | `schema_id` | string | yes | List ID | | `field` | object | yes | The new field | | `field.name` | string | yes | Field name, up to 255 characters | | `field.slug` | string | yes | Field slug: letters, digits, `-` and `_`, up to 255 characters; Latin letters are best | | `field.type` | string | yes | Field type — as in `createListSchema` | | `field.is_required` | boolean | no | Required field. `true` by default | | `field.is_hidden` | boolean | no | Hide the field from the interface. `false` by default | | `field.is_encryptable` | boolean | no | Store the value encrypted. `false` by default | | `field.currency` | string | for `money` | Only for `money`: a three-letter ISO 4217 currency code — `USD`, `EUR`, `GBP` | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/addListSchemaField" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "field": {"name": "Size, oz", "slug": "volume", "type": "number", "is_required": false} }' ``` ```json title="Response 422" { "message": "The list already has a field with this slug", "errors": { "field.slug": ["The list already has a field with this slug"] } } ``` A successful response is code `204` with no body. To see the list with the new field, call [`getListSchema`](#getlistschema). Notes and errors: - A field with this `slug` already exists — `422` with an error on `field.slug`. - A `money` field needs a currency in `field.currency`: without it, or with an unknown code — `422` with an error on `field.currency`. - If the new field is required, you will have to fill it every time you add a record. Records already in the list do not change. - The list does not exist — `404`, as in [`getListSchema`](#getlistschema); the list belongs to someone else's project — `403`. ## deleteListSchemaField Deletes a field from the list and erases its values in all records. ```endpoint GET POST https://watbot.org/api/v1/deleteListSchemaField ``` | Parameter | Type | Required | Description | |---|---|---|---| | `schema_id` | string | yes | List ID | | `slug` | string | yes | Field slug | ```bash title="Request" curl -X POST "https://watbot.org/api/v1/deleteListSchemaField" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "volume"}' ``` ```json title="Response 422" { "message": "Field not found", "errors": { "slug": ["Field not found"] } } ``` A successful response is code `204` with no body. > [!WARNING] > The field's values are erased in all records at once. They cannot be restored — just like when you [delete a field in your account](https://support.watbot.org/lists/create#deleting-a-field). Errors: - There is no field with this `slug` — `422` with an error on `slug`. - The list does not exist — `404`, as in [`getListSchema`](#getlistschema); the list belongs to someone else's project — `403`.