### Response from GET /api/meta/whoami

Source: https://tabladb.com/docs/api

This is the response from GET /api/meta/whoami. It reports the account and key details, including the key's access level and database scope. The last_used_at stamp is best-effort and may be from the previous request.

```json
{
  "user": {
    "id": "usr_7k2mnpq4rstv",
    "email": "tarek@example.com",
    "name": "Tarek Shalaby"
  },
  "key": {
    "id": "key_3n7pqrs2tuvw",
    "name": "Automation platform",
    "created_at": "2026-07-11T09:14:02.118Z",
    "last_used_at": "2026-07-22T15:31:44.902Z",
    "access": "read_write",
    "databases": "all"
  }
}

```

--------------------------------

### GET /api/databases

Source: https://tabladb.com/docs/api

Lists every database the credential is a member of.

```APIDOC
## GET /api/databases

### Description
Lists every database the credential is a member of.

### Method
GET

### Endpoint
/api/databases

### Response
#### Success Response (200)
- **databases** (array) - List of database objects.

#### Response Example
{
  "databases": [
    {
      "id": "database_id",
      "name": "database_name",
      "color": "emerald"
    }
  ]
}
```

--------------------------------

### GET /api/meta/whoami

Source: https://tabladb.com/docs/api

Verifies an API key and returns the associated user and key details. It requires no database or table id, so it can be called before any other configuration.

```APIDOC
## GET /api/meta/whoami

### Description
Verifies an API key and returns the associated user and key details. It requires no database or table id, so it can be called before any other configuration.

### Method
GET

### Endpoint
/api/meta/whoami

### Authentication
Requires an API key in the Authorization header: `Authorization: Bearer <key_id>.<secret>`

### Response
#### Success Response (200)
- **user** (object) - The user associated with the key.
  - **id** (string) - User ID.
  - **email** (string) - User email.
  - **name** (string) - User name.
- **key** (object) - The API key details.
  - **id** (string) - Key ID.
  - **name** (string) - Key name.
  - **created_at** (string) - Key creation timestamp.
  - **last_used_at** (string) - Last used timestamp (best-effort).
  - **access** (string) - Key access level (e.g., read_write).
  - **databases** (string or array) - Either "all" or the list of database IDs the key is narrowed to.

#### Response Example
{
  "user": {
    "id": "usr_7k2mnpq4rstv",
    "email": "tarek@example.com",
    "name": "Tarek Shalaby"
  },
  "key": {
    "id": "key_3n7pqrs2tuvw",
    "name": "Automation platform",
    "created_at": "2026-07-11T09:14:02.118Z",
    "last_used_at": "2026-07-22T15:31:44.902Z",
    "access": "read_write",
    "databases": "all"
  }
}

### Error Handling
- **401 Unauthorized** - Missing or invalid API key.
  - Response body: {"error":{"code":"unauthorized","message":"Missing or invalid API key. Expected: Bearer <id>.<secret>."}}
```

--------------------------------

### GET /api/databases/:id/webhooks

Source: https://tabladb.com/docs/api

Lists a database's webhooks. Requires viewer role or higher.

```APIDOC
## GET /api/databases/:id/webhooks

### Description
List a database's webhooks. Viewer and up.

### Method
GET

### Endpoint
/api/databases/:id/webhooks

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID.

### Response
#### Success Response (200)
- **webhooks** (array) - List of webhook objects.

#### Response Example
{
  "webhooks": [
    {
      "id": "whk_ntdbgfuyu8ya",
      "database_id": "db_d2dbgdm3r8y3",
      "table_id": "tbl_6xie9dkuw2sa",
      "name": "Bookings changed",
      "url": "https://example.com/hook",
      "trigger_type": "record_created",
      "payload_key": "id",
      "secret": "whsec_…",
      "is_active": true,
      "conditions": null,
      "watched_field_ids": null,
      "consecutive_failures": 0,
      "last_status": null,
      "last_attempt_at": null,
      "paused_at": null,
      "created_at": "2026-08-17T20:29:12.004Z"
    }
  ]
}
```

--------------------------------

### List records with filter: GET and POST forms

Source: https://tabladb.com/docs/api

Two equivalent ways to list records with a filter. The GET form URL-encodes the filter in the query string; the POST form sends it as a JSON object in the request body. Both return the same page shape.

```http
GET /api/tables/tbl_xhxth3zynfwi/records?filter=%7B%22conditions%22%3A%5B%7B%22field%22%3A%22Status%22%2C%22op%22%3A%22is%22%2C%22value%22%3A%22Confirmed%22%7D%5D%7D&sort=-Check-in&page_size=50
```

```http
POST /api/tables/tbl_xhxth3zynfwi/records/list
{
  "filter": { "join": "or", "conditions": [
    { "field": "Status", "op": "is", "value": "Confirmed" },
    { "field": "Nights", "op": "greater_or_equal", "value": 3 }
  ] },
  "sort": "Status,Nightly rate:desc",
  "page_size": 50
}
```

--------------------------------

### GET /api/databases/:id/tables

Source: https://tabladb.com/docs/api

Lists the database's tables, each with its fields.

```APIDOC
## GET /api/databases/:id/tables

### Description
Lists the database's tables, each with its fields.

### Method
GET

### Endpoint
/api/databases/:id/tables

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID.

### Response
#### Success Response (200)
- **tables** (array) - List of table objects, each with fields.

#### Response Example
{
  "tables": [
    {
      "id": "table_id",
      "name": "table_name",
      "fields": []
    }
  ]
}
```

--------------------------------

### Verify API key with GET /api/meta/whoami

Source: https://tabladb.com/docs/api

Use this request to verify an API key. It requires no database or table id, so it works before anything else is configured. A 200 response proves the key is valid; a 401 indicates a missing or invalid key.

```bash
curl https://tabladb.com/api/databases \
  -H "Authorization: Bearer key_xxxxxxxxxxxx.your-secret"

```

--------------------------------

### GET /api/tables/:id/views

Source: https://tabladb.com/docs/api

Lists the views of a table, ordered by position then created_at. This endpoint is open to any member of the database.

```APIDOC
## GET /api/tables/:id/views

### Description
Returns the views of the specified table, ordered by `position` then `created_at`.

### Method
GET

### Endpoint
/api/tables/:id/views

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the table whose views are to be listed.

### Response
#### Success Response (200)
Returns an array of view objects. Each view contains at least `id`, `name`, `config`, and `position` fields.

#### Response Example
```json
[
  {
    "id": "view_id",
    "name": "Grid view",
    "config": {},
    "position": 0
  }
]
```
```

--------------------------------

### GET /api/webhooks/:id

Source: https://tabladb.com/docs/api

Retrieves a single webhook's full configuration. Requires viewer role or higher. The signing secret is not returned.

```APIDOC
## GET /api/webhooks/:id

### Description
One webhook's full configuration. Viewer and up. The signing secret is not returned.

### Method
GET

### Endpoint
/api/webhooks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The webhook ID.

### Response
#### Success Response (200)
- **webhook** (object) - The webhook configuration, without the secret.

#### Response Example
{
  "webhook": {
    "id": "whk_ntdbgfuyu8ya",
    "database_id": "db_d2dbgdm3r8y3",
    "table_id": "tbl_6xie9dkuw2sa",
    "name": "Bookings changed",
    "url": "https://example.com/hook",
    "trigger_type": "record_created",
    "payload_key": "id",
    "is_active": true,
    "conditions": null,
    "watched_field_ids": null,
    "consecutive_failures": 0,
    "last_status": null,
    "last_attempt_at": null,
    "paused_at": null,
    "created_at": "2026-08-17T20:29:12.004Z"
  }
}
```

--------------------------------

### GET /api/health

Source: https://tabladb.com/docs/api

Checks whether the service is up and its database is answering. Returns 200 when Postgres replies, 503 when it does not. Takes no API key.

```APIDOC
## GET /api/health

### Description
Checks whether the service is up and its database is answering. Returns 200 while Postgres replies, 503 while it does not. Takes no API key.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates the service is up.
- **name** (string) - The service name, "tabla".
- **database** (boolean) - Indicates the database is answering.

#### Response Example
{"ok":true,"name":"tabla","database":true}

```

--------------------------------

### GET /api/tables/:id

Source: https://tabladb.com/docs/api

Returns a single table with its fields. Each field includes the 'operators' property.

```APIDOC
## GET /api/tables/:id

### Description
Returns a single table with its fields. Each field includes the 'operators' property.

### Method
GET

### Endpoint
/api/tables/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.

### Response
#### Success Response (200)
- **table** (object) - The table object with its fields.

#### Response Example
{
  "id": "table_id",
  "name": "table_name",
  "fields": [
    {
      "id": "field_id",
      "name": "field_name",
      "type": "text",
      "operators": ["is", "is_not", "contains", "not_contains", "empty", "not_empty"]
    }
  ]
}
```

--------------------------------

### GET /api/databases/:id/export

Source: https://tabladb.com/docs/api

Exports the entire database as a zip file. Any member of the database may export it. This route accepts a session cookie as well as a Bearer key, and refuses requests with a cross-site or same-site Sec-Fetch-Site header.

```APIDOC
## GET /api/databases/:id/export

### Description
Exports the entire database as a zip file. Any member of the database may export it. This route accepts a session cookie as well as a Bearer key, and refuses requests with a cross-site or same-site Sec-Fetch-Site header.

### Method
GET

### Endpoint
/api/databases/:id/export

### Parameters
#### Path Parameters
- **id** (string) - Required - The database identifier.

### Response
#### Success Response (200)
- **Content-Type** (string) - application/zip
- **Body** (file) - A zip archive containing:
  - **manifest.json** - Structure with exported_at, database id and name, and per table: id, name, display_field_id, fields (id, name, storage_kind, costume, options), and saved views (id, name, type, config).
  - **<table>.csv** - CSV files for each table.

### Error Handling
- **403** - The request has a Sec-Fetch-Site header of cross-site or same-site (browser-only guard).
```

--------------------------------

### POST /api/tables/:id/records/list

Source: https://tabladb.com/docs/api

List records with the same parameters as GET, but parameters are sent in the JSON request body. Useful for filters too long for a URL.

```APIDOC
## POST /api/tables/:id/records/list

### Description
List records using the same query surface as GET, but with parameters in the JSON request body. This is useful for filters too long for a web address.

### Method
POST

### Endpoint
/api/tables/:id/records/list

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.

#### Request Body
- **view** (string) - Optional - A saved view ID or name.
- **filter** (object) - Optional - Filter object.
- **sort** (string) - Optional - Comma-separated sort fields.
- **search** (string) - Optional - Search term.
- **fields** (string) - Optional - Comma-separated field list.
- **page_size** (integer) - Optional - Page size.
- **bookmark** (string) - Optional - Pagination token.
- **cell_format** (string) - Optional - 'names' or 'ids'.
- **key_by** (string) - Optional - 'name' or 'id'.
- **flat** (boolean) - Optional - Spread fields at top level.

Note: link_display_cap is not read from the body; link cells always include all display texts.

### Response
#### Success Response (200)
- **records** (array) - List of record objects.
- **bookmark** (string) - Pagination token.
- **field_ids** (object) - Field name to ID mapping.

#### Response Example
{
  "records": [
    {
      "id": "rec_hfsd6hs3nfhu",
      "created_at": "2026-07-22T15:30:20.026Z",
      "updated_at": "2026-07-22T15:30:20.026Z",
      "fields": {
        "Reference": "CM-1041",
        "Nights": 3,
        "Nightly rate": 1450,
        "Check-in": "2026-08-02",
        "Status": "Confirmed",
        "Guest": [{ "id": "rec_vkim6gua34pp", "display": "Layla Hassan" }]
      }
    }
  ],
  "bookmark": "eyJ2IjpbXSwiaWQiOiJyZWNfaGZzZDZoczNuZmh1In0",
  "field_ids": {
    "Reference": "fld_yrhs7u9v4jd7",
    "Nights": "fld_twa9psesrjx9",
    "Nightly rate": "fld_2vf9y4dn7g2t",
    "Check-in": "fld_279mx4k477yz"
  }
}
```

--------------------------------

### Webhook payload for record.updated

Source: https://tabladb.com/docs/api

Example payload for a record.updated webhook delivery. Shows the delivery_id, event, occurred_at, database and table identifiers, record_id, changed_field_ids, and field_ids mapping. Signatures are elided in the source.

```json
{
  "delivery_id": "dlv_s43ic2cv5z7i",
  "event": "record.updated",
  "occurred_at": "2026-07-22T16:20:13.950Z",
  "database": {
    "id": "db_awjakb4hxcbx",
    "name": "Casa Mayouie"
  },
  "table": {
    "id": "tbl_xhxth3zynfwi",
    "name": "Bookings"
  },
  "record_id": "rec_hfsd6hs3nfhu",
  "changed_field_ids": [
    "fld_twa9psesrjx9",
    "fld_2exr2qahjthk"
  ],
  "field_ids": {
    "Guest": "fld_3e8wmizyypxc",
    "Photo": "fld_h9y9q9nh8q68",
    "Nights": "fld_twa9psesrjx9",
    "Status": "fld_2exr2qahjthk",
    "Check-in": "fld_279mx4k477yz"
  }
}
```

--------------------------------

### GET /api/tables/:id/views

Source: https://tabladb.com/docs/api

Lists the views of a table. Used to read a single view since there is no GET for a single view.

```APIDOC
## GET /api/tables/:id/views

### Description
Lists the views of a table. Used to read a single view since there is no GET for a single view.

### Method
GET

### Endpoint
/api/tables/:id/views

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.

### Response
#### Success Response (200)
- **views** (array) - List of view objects.

#### Response Example
{
  "views": []
}
```

--------------------------------

### POST /api/databases

Source: https://tabladb.com/docs/api

Creates a new database with the given name.

```APIDOC
## POST /api/databases

### Description
Creates a new database with the given name.

### Method
POST

### Endpoint
/api/databases

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new database.

### Response
#### Success Response (200)
- **database** (object) - The created database object.

#### Response Example
{
  "id": "database_id",
  "name": "database_name",
  "color": null
}
```

--------------------------------

### Trash routes: list, restore, purge

Source: https://tabladb.com/docs/api

Lists trash records (newest first) with optional pagination, restores specific ids, and purges either specific ids or all trash. Restore refuses ids not in the trash; purge with `all: true` permanently deletes records and their attachment bytes. Role rules apply: editors and owners can delete, restore, and purge; viewers get a 403 and nothing changes.

```http
GET  /api/tables/:id/trash                 → { records: [ … deleted_at … ], bookmark? }
     ?page_size=  ?bookmark=              newest first

POST /api/tables/:id/trash/restore        { "ids": ["rec_…"] }
     → { records: [ … ] }                 refuses if an id is not in the trash

POST /api/tables/:id/trash/purge          { "ids": ["rec_…"] }  → { records: [ { id, deleted: true } ] }
POST /api/tables/:id/trash/purge          { "all": true }       → { deleted: <count> }
     gone for good, attachment bytes included
```

--------------------------------

### GET /api/tables/:id/records/:rid

Source: https://tabladb.com/docs/api

Retrieve a single record with all its fields.

```APIDOC
## GET /api/tables/:id/records/:rid

### Description
Retrieve one record by its record ID, including all fields.

### Method
GET

### Endpoint
/api/tables/:id/records/:rid

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.
- **rid** (string) - Required - The record ID.

### Response
#### Success Response (200)
- **id** (string) - Record ID.
- **created_at** (string) - Creation timestamp.
- **updated_at** (string) - Last update timestamp.
- **fields** (object) - Record fields.

#### Response Example
{
  "id": "rec_hfsd6hs3nfhu",
  "created_at": "2026-07-22T15:30:20.026Z",
  "updated_at": "2026-07-22T15:30:20.026Z",
  "fields": {
    "Reference": "CM-1041",
    "Nights": 3,
    "Nightly rate": 1450,
    "Check-in": "2026-08-02",
    "Status": "Confirmed",
    "Guest": [{ "id": "rec_vkim6gua34pp", "display": "Layla Hassan" }]
  }
}
```

--------------------------------

### POST /api/databases/:id/import

Source: https://tabladb.com/docs/api

Imports a CSV or XLSX file into a database. The route has two modes: preview (file only) and run (file, target, and plan). The preview mode parses and sniffs columns without writing, while the run mode validates and writes the data.

```APIDOC
## POST /api/databases/:id/import

### Description
Imports a CSV or XLSX file into a database. The route has two modes: preview (file only) and run (file, target, and plan). The preview mode parses and sniffs columns without writing, while the run mode validates and writes the data.

### Method
POST

### Endpoint
/api/databases/:id/import

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID.

#### Request Body (multipart/form-data)
- **file** (file) - Required - The file to import. The parser is chosen by the filename extension: .xlsx/.xls read the first worksheet only; everything else is parsed as CSV.
- **target** (JSON) - Required for run mode - Specifies the target table. Either {"mode":"new_table","name":"..."} or {"mode":"existing_table","tableId":"tbl_..."}. An existing table must belong to this database.
- **plan** (JSON list) - Required for run mode - List of column actions: {"columnIndex":0,"sourceHeader":"...","action":{...}}. Actions can be {"kind":"skip"}, {"kind":"map","targetFieldId":"fld_..."}, or {"kind":"create","name":"...","costume":"...","options":{...}}. Columns with no entry are not imported.

### Request Example
(file part: data.csv)
(target part: {"mode":"new_table","name":"Imported"})
(plan part: [{"columnIndex":0,"sourceHeader":"Name","action":{"kind":"create","name":"Name","costume":"singleLineText"}}])

### Response
#### Success Response (200)
- **rowCount** (number) - Number of data rows in the file (preview mode).
- **extraSheetsIgnored** (number) - Number of extra worksheets ignored (preview mode, for .xlsx/.xls).
- **columnIndex** (number) - Column index (preview mode, per column).
- **sourceHeader** (string) - Source header text (preview mode, per column).
- **guessedCostume** (string) - Guessed costume (preview mode, per column).
- **guessedOptions** (object) - Guessed options (preview mode, per column).
- **samples** (array) - Up to three sample values (preview mode, per column).
- **tableId** (string) - ID of the created or targeted table (run mode).
- **created** (number) - Number of rows created (run mode).

#### Response Example
{
  "rowCount": 100,
  "extraSheetsIgnored": 0,
  "columns": [
    {
      "columnIndex": 0,
      "sourceHeader": "Name",
      "guessedCostume": "singleLineText",
      "guessedOptions": {},
      "samples": ["Alice", "Bob", "Carol"]
    }
  ]
}

### Error Handling
- **bad_request** - Returned when exactly one of target/plan is sent.
- **File cap** - 20 MB of raw bytes, checked before parsing. A declared Content-Length above 22 MB is rejected before buffering.
- **Row cap** - 50,000 data rows per run, refused at preview time as well as at run time.
- **Choice cap** - A select column resolving to more than 100 distinct values is refused by name.
- **Validation** - A run validates everything before writing. A bad value on the last row aborts with nothing created. Unique-value clashes and failures during new field creation may leave partial writes.
```

--------------------------------

### POST /api/databases/:id/tables

Source: https://tabladb.com/docs/api

Creates a new table in the database with an empty field list.

```APIDOC
## POST /api/databases/:id/tables

### Description
Creates a new table in the database with an empty field list.

### Method
POST

### Endpoint
/api/databases/:id/tables

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID.

#### Request Body
- **name** (string) - Required - The name of the new table.

### Response
#### Success Response (200)
- **table** (object) - The created table object with an empty field list.

#### Response Example
{
  "id": "table_id",
  "name": "table_name",
  "fields": []
}
```

--------------------------------

### GET /api/webhooks/:id/deliveries

Source: https://tabladb.com/docs/api

Lists the 50 most recent deliveries, newest first. Requires viewer role or higher.

```APIDOC
## GET /api/webhooks/:id/deliveries

### Description
The 50 most recent deliveries, newest first. Viewer and up.

### Method
GET

### Endpoint
/api/webhooks/:id/deliveries

### Parameters
#### Path Parameters
- **id** (string) - Required - The webhook ID.

### Response
#### Success Response (200)
- **deliveries** (array) - List of delivery objects, each with status, duration, and body.
```

--------------------------------

### Create a field with POST /api/tables/:id/fields

Source: https://tabladb.com/docs/api

Creates a currency field named "Nightly rate" on the table with ID tbl_xhxth3zynfwi. The request body must include a required, non-empty, trimmed, table-unique name; a type; and an options object. A name collision returns 409, not 400. The options object may only introduce keys from the known set; an unknown key is refused with a 400 that names it and prints the valid list.

```http
POST /api/tables/tbl_xhxth3zynfwi/fields

{
  "name": "Nightly rate",
  "type": "currency",
  "options": { "symbol": "EGP", "symbol_position": "after", "decimals": 2 }
}

```

--------------------------------

### Records write request bodies (POST, PATCH, PUT, DELETE)

Source: https://tabladb.com/docs/api

Shows the four write request bodies for the records endpoint: POST creates, PATCH updates, PUT merges on a key, and DELETE removes records. The DELETE body can be replaced with the ?records= query parameter. All writes accept cell_format, key_by, and flat as query parameters.

```http
POST   { "records": [ { "fields": { "Reference": "CM-1042" } } ] }
PATCH  { "records": [ { "id": "rec_…", "fields": { "Nights": 4 } } ] }
PUT    { "merge_on": ["Reference"], "records": [ { "fields": { … } } ] }
DELETE { "records": ["rec_…"] }        or  ?records=rec_a,rec_b

```

--------------------------------

### GET /api/tables/:id/trash

Source: https://tabladb.com/docs/api

Lists records in the trash for a table, newest first. Supports pagination via page_size and bookmark parameters.

```APIDOC
## GET /api/tables/:id/trash

### Description
Lists records in the trash for a table, newest first. Supports pagination via page_size and bookmark parameters.

### Method
GET

### Endpoint
/api/tables/:id/trash

### Parameters
#### Path Parameters
- **id** (string) - Required - The table id.

#### Query Parameters
- **page_size** (integer) - Optional - Number of records per page.
- **bookmark** (string) - Optional - Pagination bookmark.

### Response
#### Success Response (200)
- **records** (array) - List of trashed records, each with deleted_at.
- **bookmark** (string) - Pagination bookmark for next page.

#### Response Example
{
  "records": [
    {
      "id": "rec_...",
      "deleted_at": "2026-07-22T15:30:20.026Z"
    }
  ],
  "bookmark": "..."
}
```

--------------------------------

### Create record with attachment URL via POST /api/tables/:id/records

Source: https://tabladb.com/docs/api

Create a record with a file in one call by putting a URL or an object with url and filename directly into the attachment field. Tabla fetches the link during the write, so no separate attachment id is needed.

```http
POST /api/tables/tbl_xhxth3zynfwi/records

{
  "records": [{
    "fields": {
      "Reference": "CM-1043",
      "Photos": [
        "https://example.com/terrace.png",
        { "url": "https://example.com/receipt?id=88", "filename": "receipt.pdf" }
      ]
    }
  }]
}
```

--------------------------------

### POST /api/databases/:id/webhooks

Source: https://tabladb.com/docs/api

Creates a new webhook. Requires editor role or higher. The response includes the webhook object with its signing secret, which is shown only once.

```APIDOC
## POST /api/databases/:id/webhooks

### Description
Create one webhook. `url` and `trigger_type` are required; `name`, `table_id`, `conditions`, `watched_field_ids`, `payload_key` are optional. Editor and up.

### Method
POST

### Endpoint
/api/databases/:id/webhooks

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID.

#### Request Body
- **url** (string) - Required - The endpoint URL.
- **trigger_type** (string) - Required - The trigger type (e.g., record_created).
- **name** (string) - Optional - The webhook name.
- **table_id** (string) - Optional - The table ID.
- **conditions** (object) - Optional - Conditions for triggering.
- **watched_field_ids** (array) - Optional - List of field IDs to watch.
- **payload_key** (string) - Optional - The payload key.

### Request Example
{
  "url": "https://example.com/hook",
  "trigger_type": "record_created",
  "name": "Bookings changed",
  "table_id": "tbl_6xie9dkuw2sa",
  "payload_key": "id"
}

### Response
#### Success Response (200)
- **webhook** (object) - The created webhook object, including the signing secret.

#### Response Example
{
  "webhook": {
    "id": "whk_ntdbgfuyu8ya",
    "database_id": "db_d2dbgdm3r8y3",
    "table_id": "tbl_6xie9dkuw2sa",
    "name": "Bookings changed",
    "url": "https://example.com/hook",
    "trigger_type": "record_created",
    "payload_key": "id",
    "secret": "whsec_…",
    "is_active": true,
    "conditions": null,
    "watched_field_ids": null,
    "consecutive_failures": 0,
    "last_status": null,
    "last_attempt_at": null,
    "paused_at": null,
    "created_at": "2026-08-17T20:29:12.004Z"
  }
}
```

--------------------------------

### GET /api/tables/:id/records

Source: https://tabladb.com/docs/api

Lists records from a table with filtering, sorting, and pagination. The filter is provided as URL-encoded JSON in the filter query parameter.

```APIDOC
## GET /api/tables/:id/records

### Description
Lists records from a table with filtering, sorting, and pagination. The filter is provided as URL-encoded JSON in the filter query parameter.

### Method
GET

### Endpoint
/api/tables/:id/records

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.

#### Query Parameters
- **filter** (string) - Optional - URL-encoded JSON filter object.
- **sort** (string) - Optional - Comma-separated sort terms.
- **page_size** (integer) - Optional - Number of records per page.
- **search** (string) - Optional - Case-insensitive substring search across text fields.
- **fields** (string) - Optional - Comma-separated list of fields to include.

### Request Example
GET /api/tables/tbl_xhxth3zynfwi/records?filter=%7B%22conditions%22%3A%5B%7B%22field%22%3A%22Status%22%2C%22op%22%3A%22is%22%2C%22value%22%3A%22Confirmed%22%7D%5D%7D&sort=-Check-in&page_size=50

### Response
#### Success Response (200)
- **records** (array) - List of record objects.
- **bookmark** (string) - Opaque pagination token for the next page.

#### Response Example
{
  "bookmark": "eyJ2IjpbXSwiaWQiOiJyZWNfaGZzZDZoczNuZmh1In0"
}
```

--------------------------------

### GET /api/tables/:id/records

Source: https://tabladb.com/docs/api

List records from a table with optional filtering, sorting, searching, and pagination. Returns a list of records and a bookmark for pagination.

```APIDOC
## GET /api/tables/:id/records

### Description
List records from a table. Supports filtering, sorting, searching, and pagination via query parameters.

### Method
GET

### Endpoint
/api/tables/:id/records

### Parameters
#### Path Parameters
- **id** (string) - Required - The table ID.

#### Query Parameters
- **view** (string) - Optional - A saved view ID (viw_...) or name. Applies the view's filter, sort, and visible fields. Explicit parameters override view settings; filter is ANDed with the view's filter.
- **filter** (string) - Optional - URL-encoded JSON filter object. Invalid JSON or non-object returns 400. A condition naming a missing field returns 400.
- **sort** (string) - Optional - Comma-separated list of field IDs or names. Prefix with '-' or suffix ':desc' for descending. Sortable storage kinds: text, long text, number, date, checkbox, single select. Unsortable kinds return 400.
- **search** (string) - Optional - Case-insensitive substring match across text and long-text columns. Literal % and _ are escaped.
- **fields** (string) - Optional - Comma-separated list of field IDs or names to include in each record's fields.
- **page_size** (integer) - Optional - Number of records per page. Default 100, max 1000. Outside range returns 400.
- **bookmark** (string) - Optional - Opaque pagination token from previous response. Must be used with the same sort/view; otherwise returns 400.
- **cell_format** (string) - Optional - 'names' (default) or 'ids' for select cells. Other values return 400.
- **key_by** (string) - Optional - 'name' (default) or 'id' for record cell keys. Other values return 400.
- **flat** (boolean) - Optional - If true, spreads record fields at top level. Accepts true/1 or false/0; other values return 400.
- **link_display_cap** (integer) - Optional - GET only. Maximum number of linked record display texts per cell. Values outside 1-1000 are ignored.

### Response
#### Success Response (200)
- **records** (array) - List of record objects.
- **bookmark** (string) - Pagination token for next page.
- **field_ids** (object) - Mapping of field names to field IDs.

#### Response Example
{
  "records": [
    {
      "id": "rec_hfsd6hs3nfhu",
      "created_at": "2026-07-22T15:30:20.026Z",
      "updated_at": "2026-07-22T15:30:20.026Z",
      "fields": {
        "Reference": "CM-1041",
        "Nights": 3,
        "Nightly rate": 1450,
        "Check-in": "2026-08-02",
        "Status": "Confirmed",
        "Guest": [{ "id": "rec_vkim6gua34pp", "display": "Layla Hassan" }]
      }
    }
  ],
  "bookmark": "eyJ2IjpbXSwiaWQiOiJyZWNfaGZzZDZoczNuZmh1In0",
  "field_ids": {
    "Reference": "fld_yrhs7u9v4jd7",
    "Nights": "fld_twa9psesrjx9",
    "Nightly rate": "fld_2vf9y4dn7g2t",
    "Check-in": "fld_279mx4k477yz"
  }
}
```