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 page.

getListSchemas

Returns the lists of all projects owned by the key holder, 50 per page.

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

Parameter	Type	Required	Description
`page`	integer	no	Page number, `1` by default

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

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.

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

Parameter	Type	Required	Description
`schema_id`	string	yes	List ID

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

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

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.

GETPOSThttps://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
`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

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

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

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.

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

Parameter	Type	Required	Description
`schema_id`	string	yes	List ID

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

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.
The list belongs to someone else's project — 403.

addListSchemaField

Adds a field to the end of the list.

GETPOSThttps://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`

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

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.

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; the list belongs to someone else's project — 403.

deleteListSchemaField

Deletes a field from the list and erases its values in all records.

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

Parameter	Type	Required	Description
`schema_id`	string	yes	List ID
`slug`	string	yes	Field slug

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

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.

Errors:

There is no field with this slug — 422 with an error on slug.
The list does not exist — 404, as in getListSchema; the list belongs to someone else's project — 403.

Lists and fields#

getListSchemas#

getListSchema#

createListSchema#

deleteListSchema#

addListSchemaField#

deleteListSchemaField#

Lists and fields

getListSchemas

getListSchema

createListSchema

deleteListSchema

addListSchemaField

deleteListSchemaField