Списки й поля

Методи цієї сторінки працюють зі схемою списку — назвою та полями. Як влаштовані поля і які в них бувають типи, описано на сторінці Списки.

getListSchemas

Повертає списки всіх проєктів, власник яких — власник ключа, по 50 на сторінку.

GETPOSThttps://watbot.org/api/v1/getListSchemas

Параметр	Тип	Обов'язковий	Опис
`page`	ціле число	ні	Номер сторінки, за замовчуванням `1`

Запит

curl -X POST "https://watbot.org/api/v1/getListSchemas" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

Відповідь 200

{
  "data": [
    {
      "id": "6650a1f2c3d4e5f6a7b8c9d0",
      "fields": {
        "nazva": {
          "name": "Назва",
          "type": "string",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        },
        "tsina": {
          "name": "Ціна",
          "type": "money",
          "currency": "UAH",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        }
      },
      "name": "Меню кафе",
      "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
  }
}

Поля списку у відповіді:

Поле	Опис
`id`	Id списку
`fields`	Поля: ключ — `slug`, значення — назва (`name`), тип (`type`) і налаштування. У грошового поля є `currency`. У полів, створених у кабінеті, можуть бути й інші ключі
`name`	Назва списку
`bot_id`	Бот, у якому створено список; `null`, якщо список створено в проєкті
`project`	UUID проєкту, якому належить список
`is_menu`	Застаріла позначка, на роботу списку не впливає
`created_at`, `updated_at`	Коли список створено і змінено востаннє

Особливості:

Розмір сторінки — 50 списків, змінити його не можна. Скільки всього сторінок — у meta.last_page, адреса наступної — у links.next.
Списки проєктів, до яких вас запросили співробітником, у відповідь не потрапляють: API працює лише з проєктами власника ключа.

getListSchema

Повертає один список із полями.

GETPOSThttps://watbot.org/api/v1/getListSchema

Параметр	Тип	Обов'язковий	Опис
`schema_id`	рядок	так	Id списку

Запит

curl -X POST "https://watbot.org/api/v1/getListSchema" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'

Відповідь 200

{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "nazva": {
        "name": "Назва",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "tsina": {
        "name": "Ціна",
        "type": "money",
        "currency": "UAH",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Меню кафе",
    "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"
  }
}

Відповідь 404

{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}

Помилки:

Списку немає або його видалено — 404. Текст помилки — в error і message; для сумісності він же лежить у errors.schema_id.
Список із чужого проєкту — 403.

createListSchema

Створює список із полями — у проєкті або в боті.

GETPOSThttps://watbot.org/api/v1/createListSchema

Параметр	Тип	Обов'язковий	Опис
`name`	рядок	так	Назва списку, до 255 символів
`project_uuid`	рядок	так, якщо немає `bot_id`	UUID проєкту, у якому створити список
`bot_id`	ціле число	так, якщо немає `project_uuid`	Номер бота: список потрапить до проєкту цього бота й буде позначений як створений у ньому. Якщо передано обидва параметри, використовується `bot_id`
`fields`	масив	так	Поля списку — від 1 до 30
`fields[].name`	рядок	так	Назва поля, до 255 символів
`fields[].slug`	рядок	так	Ім'я поля: літери, цифри, `-` і `_`, до 255 символів; краще латиницею. Не повторюється в межах списку й не збігається зі службовими іменами
`fields[].type`	рядок	так	Тип поля: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot`
`fields[].currency`	рядок	ні	Лише для `money`: трилітерний код валюти за ISO 4217 — `UAH`, `USD`, `EUR`. За замовчуванням `USD`. Невідомий код — `422`
`fields[].is_required`	логічний	ні	Обов'язкове поле. За замовчуванням `true`
`fields[].is_hidden`	логічний	ні	Приховати поле з інтерфейсу. За замовчуванням `false`
`fields[].is_encryptable`	логічний	ні	Зберігати значення зашифрованим. За замовчуванням `false`
`is_menu`	логічний	ні	Застаріла позначка, на роботу списку не впливає

Запит

curl -X POST "https://watbot.org/api/v1/createListSchema" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "name": "Меню кафе",
    "fields": [
      {"name": "Назва", "slug": "nazva", "type": "string"},
      {"name": "Ціна", "slug": "tsina", "type": "money", "currency": "UAH"},
      {"name": "Фото", "slug": "foto", "type": "image", "is_required": false},
      {"name": "У наявності", "slug": "v_naiavnosti", "type": "bool", "is_required": false}
    ]
  }'

Відповідь 201

{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "nazva": {
        "name": "Назва",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "tsina": {
        "name": "Ціна",
        "type": "money",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false,
        "currency": "UAH"
      },
      "foto": {
        "name": "Фото",
        "type": "image",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      },
      "v_naiavnosti": {
        "name": "У наявності",
        "type": "bool",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Меню кафе",
    "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"
  }
}

Відповідь 422

{
  "message": "The slug is reserved.",
  "errors": {
    "fields.0.slug": ["The slug is reserved."]
  }
}

Особливості й помилки:

Поля стають у список у тому порядку, у якому їх передано.
Створити список можна лише у своєму проєкті або своєму боті. Бот чи проєкт іншого акаунта, зокрема той, до якого вас запросили співробітником, — 403.
bot_id або project_uuid, якого не існує, — 422.
slug, що повторюється, — 422 з помилкою в полі fields.N.slug, де N — номер поля в масиві, починаючи з нуля.
Невідомий код валюти — 422 з помилкою в полі fields.N.currency.
У проєкті вже 5000 списків — 403: {"message": "A project cannot have more than 5000 lists", "error": "A project cannot have more than 5000 lists"}.
У GET-запиті поля передаються в адресі так: fields[0][name]=Назва&fields[0][slug]=nazva&fields[0][type]=string. Зручніше надсилати POST із JSON.

deleteListSchema

Видаляє список разом із його записами.

GETPOSThttps://watbot.org/api/v1/deleteListSchema

Параметр	Тип	Обов'язковий	Опис
`schema_id`	рядок	так	Id списку

Запит

curl -X POST "https://watbot.org/api/v1/deleteListSchema" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'

Відповідь 404

{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}

Успішна відповідь — код 204 без тіла.

Особливості й помилки:

Перед видаленням перевірте, що список не вибрано в блоках ботів: після видалення блоки не знайдуть записів.
Після видалення записи списку не знаходяться ні в getListItems, ні за item_id: updateListItem і deleteListItem відповідають 404.
Списку немає або його вже видалено — 404, як у getListSchema.
Список із чужого проєкту — 403.

addListSchemaField

Додає поле в кінець списку.

GETPOSThttps://watbot.org/api/v1/addListSchemaField

Параметр	Тип	Обов'язковий	Опис
`schema_id`	рядок	так	Id списку
`field`	об'єкт	так	Нове поле
`field.name`	рядок	так	Назва поля, до 255 символів
`field.slug`	рядок	так	Ім'я поля: літери, цифри, `-` і `_`, до 255 символів; краще латиницею
`field.type`	рядок	так	Тип поля — як у `createListSchema`
`field.is_required`	логічний	ні	Обов'язкове поле. За замовчуванням `true`
`field.is_hidden`	логічний	ні	Приховати поле з інтерфейсу. За замовчуванням `false`
`field.is_encryptable`	логічний	ні	Зберігати значення зашифрованим. За замовчуванням `false`
`field.currency`	рядок	для `money`	Лише для `money`: трилітерний код валюти за ISO 4217 — `UAH`, `USD`, `EUR`

Запит

curl -X POST "https://watbot.org/api/v1/addListSchemaField" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "field": {"name": "Обʼєм, мл", "slug": "obiem", "type": "number", "is_required": false}
  }'

Відповідь 422

{
  "message": "The list already has a field with this slug",
  "errors": {
    "field.slug": ["The list already has a field with this slug"]
  }
}

Успішна відповідь — код 204 без тіла. Щоб побачити список із новим полем, викличте getListSchema.

Особливості й помилки:

Поле з таким slug уже є — 422 з помилкою в field.slug.
Для поля money потрібна валюта field.currency: без неї або з невідомим кодом — 422 з помилкою в field.currency.
Якщо нове поле обов'язкове, його доведеться заповнювати під час кожного додавання запису. Записи, які вже є в списку, не змінюються.
Списку немає — 404, як у getListSchema; список із чужого проєкту — 403.

deleteListSchemaField

Видаляє поле зі списку й стирає його значення в усіх записах.

GETPOSThttps://watbot.org/api/v1/deleteListSchemaField

Параметр	Тип	Обов'язковий	Опис
`schema_id`	рядок	так	Id списку
`slug`	рядок	так	Ім'я поля

Запит

curl -X POST "https://watbot.org/api/v1/deleteListSchemaField" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "obiem"}'

Відповідь 422

{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}

Успішна відповідь — код 204 без тіла.

Увага

Значення поля стираються в усіх записах одразу. Повернути їх не можна — так само, як під час видалення поля в кабінеті.

Помилки:

Поля з таким slug немає — 422 з помилкою в slug.
Списку немає — 404, як у getListSchema; список із чужого проєкту — 403.

Списки й поля#

getListSchemas#

getListSchema#

createListSchema#

deleteListSchema#

addListSchemaField#

deleteListSchemaField#

Списки й поля

getListSchemas

getListSchema

createListSchema

deleteListSchema

addListSchemaField

deleteListSchemaField