Records

The methods on this page work with list records. Field values are sent in the data object: the key is the field's slug, the value is in the format of its type. The formats of all types are described on the Lists page.

getListItems

Returns the records of a list page by page — with filtering by field values and sorting.

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

Parameter	Type	Required	Description
`schema_id`	string	yes	List ID
`limit`	integer	no	Records per page — from 1 to 1000, 50 by default
`page`	integer	no	Page number, `1` by default
`order_by`	string	no	Sorting: the field's `slug` and the direction separated by a comma — `price,desc`. The direction is `asc` (ascending, the default) or `desc`. You can also sort by `created_at` and `updated_at`. Any other field or direction — `422`
`filters`	object	no	Filtering by field values — see below
`contact_id`	integer	no	Only records linked to this contact through a `contact` field
`bot_id`	integer	no	Only records linked to this bot through a `bot` field

For example, lattes of 12 oz and more, largest first:

Request

curl -X POST "https://watbot.org/api/v1/getListItems" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "filters": {"volume": ">=,12", "title": "like,%latte%"},
    "order_by": "volume,desc",
    "limit": 20
  }'

Response 200

{
  "data": [
    {
      "id": "6650b7a1c3d4e5f6a7b8c9e1",
      "created_at": "2026-10-03T08:05:00+00:00",
      "updated_at": "2026-10-03T08:05:00+00:00",
      "title": "Oat milk latte",
      "price": 5.25,
      "photo": {
        "type": "image",
        "mime_type": "image/jpeg",
        "created_at": null,
        "name": "latte.jpg",
        "size": 0,
        "storage": "url",
        "caption": null,
        "meta": {"width": null, "height": null, "duration": null, "codec": null},
        "url": "https://example.com/menu/latte.jpg"
      },
      "in_stock": true,
      "volume": 16
    }
  ],
  "links": {
    "first": "…/v1/getListItems?page=1",
    "last": "…/v1/getListItems?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "…/v1/getListItems",
    "per_page": 20,
    "to": 1,
    "total": 1
  }
}

Response 422

{
  "message": "The limit field must not be greater than 1000.",
  "errors": {
    "limit": ["The limit field must not be greater than 1000."]
  }
}

Each record contains id, created_at, updated_at and the values of all list fields, including hidden and encrypted ones (decrypted). If a record is linked to a contact or a bot, it also has contact_id or bot_id.

Filtering

In filters, the key is the field's slug and the value is one of:

"value" or just a JSON value — the field equals the value: {"title": "Cappuccino"}, {"volume": 12}, {"in_stock": true};
"operator,value" — a comparison: {"volume": ">=,12"}.

Operator	Meaning
`=`	equals
`!=`, `<>`	not equal
`<`, `<=`, `>`, `>=`	less than, less than or equal, greater than, greater than or equal
`like`	matches a pattern: `%` — any characters, `_` — one character. Case does not matter. Without `%`, the whole value must match
`not like`	does not match a pattern

An operator is recognized only if the text before the first comma is an operator from the table. Otherwise the whole string is the value: {"title": "Flat white, large"} finds the record "Flat white, large". If the value itself starts with an operator and a comma, such as ">, 5", set the operator explicitly: "=,>, 5".

Conditions on different fields are combined with "and".

How the value is compared depends on the field type:

Field type	Filter value	Operators
`string`	Text. A JSON number is compared as text	all
`number`	A number: `12`, `"12"`, `"4.5"`	all except `like` and `not like`
`money`	An amount in main units, as when writing: `5` or `"4.99"`	all except `like` and `not like`
`bool`	`true`, `false`, `"true"`, `"false"`, `1`, `0`	`=`, `!=`
`date`	A date: `"2026-10-15"`. The day is compared in UTC: `"2026-10-15"` also finds a record dated October 15, 14:30, and `"<=,2026-10-15"` finds everything up to the end of that day	all except `like` and `not like`
`datetime`	A date and time: `"2026-10-15 14:30"` or `"2026-10-15T14:30:00+03:00"`. Time without a time zone is UTC	all except `like` and `not like`
`contact`, `bot`	A contact or bot ID	all except `like` and `not like`

A like or not like pattern can be up to 255 characters long with at most 10 % signs; several % in a row count as one.

A value that does not suit the field (text in a number field, like on an amount, an object instead of a value) — 422 with an error on filters.<slug>. If filters is not an object, the error is on filters.

A condition is skipped without an error if the list has no field with this slug, the field is encrypted, it is a file or an image, or the value is null.

In a GET request, filters are passed in the address: filters[volume]=>=,12. Encode special characters: % as %25.

Pages

The total number of records and pages is in meta.total and meta.last_page, the address of the next page is in links.next (null on the last one). Without order_by the order of records is not defined: when going through pages, set a sort order, for example created_at.

Errors:

The list does not exist — 404: {"message": "Schema not found", "error": "Schema not found", "errors": {"schema_id": ["Schema not found"]}}.
The list belongs to someone else's project — 403.
Invalid order_by or filters — 422.

addListItem

Adds a record to a list.

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

Parameter	Type	Required	Description
`schema_id`	string	yes	List ID
`data`	object	yes	Field values: the key is the `slug`, the value is in the format of the field type

Request

curl -X POST "https://watbot.org/api/v1/addListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "data": {
      "title": "Cappuccino",
      "price": 4.5,
      "photo": {
        "url": "https://example.com/menu/cappuccino.jpg",
        "storage": "url",
        "name": "cappuccino.jpg",
        "type": "image"
      },
      "in_stock": true,
      "volume": 12
    }
  }'

Response 201

{
  "data": {
    "id": "6650b7a1c3d4e5f6a7b8c9e2",
    "created_at": "2026-10-03T08:10:00+00:00",
    "updated_at": "2026-10-03T08:10:00+00:00",
    "title": "Cappuccino",
    "price": 4.5,
    "photo": {
      "type": "image",
      "mime_type": null,
      "created_at": null,
      "name": "cappuccino.jpg",
      "size": 0,
      "storage": "url",
      "caption": null,
      "meta": {"width": null, "height": null, "duration": null, "codec": null},
      "url": "https://example.com/menu/cappuccino.jpg"
    },
    "in_stock": true,
    "volume": 12
  }
}

Response 422

{
  "message": "The data.title field is required.",
  "errors": {
    "data.title": ["The data.title field is required."]
  }
}

Notes and errors:

Required fields (is_required: true) must be filled, otherwise 422. Fields missing from data stay empty. Keys that are not fields of the list are ignored.
A value of the wrong type — 422 with an error on data.<slug>: for example, text in a number field or a contact ID that does not exist.
Someone else's contact or bot in contact and bot fields — 403.
Dates in the response are strings in UTC, as in getListItems: "2026-10-15T00:00:00.000000Z".
The list does not exist — 404, as in getListItems; the list belongs to someone else's project — 403.

updateListItem

Changes the field values of a record. Fields missing from data do not change.

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

Parameter	Type	Required	Description
`item_id`	string	yes	Record ID
`data`	object	yes	New field values: the key is the `slug`, the value is in the format of the field type

For example, a new price and the "out of stock" mark:

Request

curl -X POST "https://watbot.org/api/v1/updateListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "6650b7a1c3d4e5f6a7b8c9e2",
    "data": {"price": 4.75, "in_stock": false}
  }'

Response 200

{
  "data": {
    "id": "6650b7a1c3d4e5f6a7b8c9e2",
    "created_at": "2026-10-03T08:10:00+00:00",
    "updated_at": "2026-10-03T09:30:00+00:00",
    "title": "Cappuccino",
    "price": 4.75,
    "photo": {
      "type": "image",
      "mime_type": null,
      "created_at": null,
      "name": "cappuccino.jpg",
      "size": 0,
      "storage": "url",
      "caption": null,
      "meta": {"width": null, "height": null, "duration": null, "codec": null},
      "url": "https://example.com/menu/cappuccino.jpg"
    },
    "in_stock": false,
    "volume": 12
  }
}

Response 404

{
  "message": "Item not found",
  "error": "Item not found",
  "errors": {
    "item_id": ["Item not found"]
  }
}

The response contains the whole record.

Notes and errors:

Only the fields you send are validated. A required field cannot be sent empty — 422.
This method cannot clear a field: null and empty values are skipped, and the field keeps its previous value.
Dates in the response are strings in UTC, as in getListItems.
The record does not exist, has been deleted, or its list has been deleted — 404. The error text is in error and message; for compatibility it is also in errors.item_id.
The record belongs to a list in someone else's project — 403.

deleteListItem

Deletes a record.

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

Parameter	Type	Required	Description
`item_id`	string	yes	Record ID

Request

curl -X POST "https://watbot.org/api/v1/deleteListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "6650b7a1c3d4e5f6a7b8c9e2"}'

Response 404

{
  "message": "Item not found",
  "error": "Item not found",
  "errors": {
    "item_id": ["Item not found"]
  }
}

A successful response is code 204 with no body.

Errors:

The record does not exist, has already been deleted, or its list has been deleted — 404, as in updateListItem.
The record belongs to a list in someone else's project — 403.

Records#

getListItems#

Filtering#

Pages#

addListItem#

updateListItem#

deleteListItem#

Records

getListItems

Filtering

Pages

addListItem

updateListItem

deleteListItem