# Create, read, update and delete records

> List, get, create, update and delete records in a Tadabase table through the REST API, and the API key permission each call needs.

Source: https://tadabase.com/docs/developers/working-with-records  
Status: Verified Nov 17, 2026. Checked against the current product

The REST API reads and changes the records of one table at a time, at `https://api.tadabase.io/api/v1/data-tables/{tableId}/records`. Use it to sync records with another system or to change them from your own code.

## The record endpoints

| Action | Method and path | API key permission |
| --- | --- | --- |
| List records | `GET /data-tables/{tableId}/records` | **Allow Reads** |
| Get one record | `GET /data-tables/{tableId}/records/{recordId}` | **Allow Reads** |
| Create a record | `POST /data-tables/{tableId}/records` | **Allow Updates** |
| Update a record | `POST /data-tables/{tableId}/records/{recordId}` | **Allow Updates** |
| Delete a record | `DELETE /data-tables/{tableId}/records/{recordId}` | **Allow Delete** |

Every request sends the three headers `X-Tadabase-App-id`, `X-Tadabase-App-Key` and `X-Tadabase-App-Secret`. If the key does not have the permission in the table, the API answers HTTP 412 with "The method being used is disabled for this API key." Your plan must also include API access.

> **Note:** Updates use `POST` to the record's URL. `PUT` is not accepted for records.

`{tableId}` is the table's ID and the body uses field slugs such as `field_36`. Get both from [Read your tables, fields and roles](https://tadabase.com/docs/developers/tables-and-fields-api).

## List records

```bash
curl -G "https://api.tadabase.io/api/v1/data-tables/{tableId}/records" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  --data-urlencode "limit=50" \
  --data-urlencode "page=1" \
  --data-urlencode "fields=field_36,field_37"
```

```js
const BASE = 'https://api.tadabase.io/api/v1';
const headers = {
  'X-Tadabase-App-id': 'YOUR_APP_ID',
  'X-Tadabase-App-Key': 'YOUR_API_KEY',
  'X-Tadabase-App-Secret': 'YOUR_API_SECRET',
};

const params = new URLSearchParams({ limit: '50', page: '1', fields: 'field_36,field_37' });
const res = await fetch(`${BASE}/data-tables/${tableId}/records?${params}`, { headers });
const data = await res.json();
console.log(data.items, data.total_items);
```

The response:

```json
{
  "type": "success",
  "items": [
    { "id": "K2ejlOQo9B", "field_36": "Ada", "field_37": "ada@example.com" }
  ],
  "total_items": 1,
  "total_pages": 1,
  "current_page": 1,
  "limit": 50
}
```

| Query parameter | What it does |
| --- | --- |
| `page` | The page to return, starting at 1. |
| `limit` | Records per page. 100 is the most, and the default. |
| `fields` | Comma-separated field slugs to return. You can also ask for `id`, `created_at`, `updated_at` and `created_by`. Unknown names are ignored; if every name is unknown, the API answers HTTP 400. |
| `display_names` | `1` keys each value by the field's name instead of its slug. |
| `filters` | Return only matching records. See [Filter records in API requests](https://tadabase.com/docs/developers/filtering-records). |
| `order`, `order_by`, `sort_by` | Sort the list. See [Sort and page through records](https://tadabase.com/docs/developers/sorting-and-pagination). |

A connection field comes back twice: `field_40` holds the connected record IDs and `field_40_val` holds each ID with its display value. [Field value formats in the API](https://tadabase.com/docs/developers/field-types-reference) shows how every field type comes back.

## Get one record

```bash
curl "https://api.tadabase.io/api/v1/data-tables/{tableId}/records/{recordId}" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET"
```

```js
const res = await fetch(`${BASE}/data-tables/${tableId}/records/${recordId}`, { headers });
const { type, item, msg } = await res.json();
if (type !== 'success') throw new Error(msg);
```

```json
{
  "type": "success",
  "item": { "id": "K2ejlOQo9B", "field_36": "Ada", "field_37": "ada@example.com" }
}
```

Add `?display_names=1` to key the values by field name. A record that does not exist comes back as `{"type":"error","msg":"Record Was Not Found."}` with HTTP status 200, so check `type`, not only the status code.

## Create a record

Send the values as JSON (or as form data) with field slugs as keys. Fields you leave out stay empty.

```bash
curl -X POST "https://api.tadabase.io/api/v1/data-tables/{tableId}/records" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"field_36": "Ada Lovelace", "field_37": "ada@example.com"}'
```

```js
const res = await fetch(`${BASE}/data-tables/${tableId}/records`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ field_36: 'Ada Lovelace', field_37: 'ada@example.com' }),
});
const { type, recordId, msg } = await res.json();
```

```json
{
  "type": "success",
  "recordId": "K2ejlOQo9B",
  "msg": "The record has been successfully saved."
}
```

- Add `?return=true` to the URL to get the saved record back in `record`.
- If a field has a **Default Record Value** in its settings, that value is saved when you leave the field out or send it blank.
- To upload a file, send the request as `multipart/form-data`. [Field value formats in the API](https://tadabase.com/docs/developers/field-types-reference) shows the format for every field type, files included.

## Update a record

Post to the record's URL. Only the fields you send change; every other field keeps its value. Send an empty value to clear a field.

```bash
curl -X POST "https://api.tadabase.io/api/v1/data-tables/{tableId}/records/{recordId}" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"field_38": "Inactive"}'
```

```js
const res = await fetch(`${BASE}/data-tables/${tableId}/records/${recordId}`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ field_38: 'Inactive' }),
});
const { type, msg } = await res.json();
```

The response is the same as for a create, with the record's ID in `recordId`.

## Delete a record

```bash
curl -X DELETE "https://api.tadabase.io/api/v1/data-tables/{tableId}/records/{recordId}" \
  -H "X-Tadabase-App-id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET"
```

```js
const res = await fetch(`${BASE}/data-tables/${tableId}/records/${recordId}`, { method: 'DELETE', headers });
const { type, msg } = await res.json();
```

```json
{
  "type": "success",
  "msg": "The record has been successfully deleted."
}
```

A record that does not exist answers HTTP 404. Deleting a record runs the table's delete webhooks and recalculates the equations that depend on it.

> **Warning:** A deleted record cannot be brought back through the API. If **Log Deleted Records** is on for the table, a copy is kept in the record logs. See [Track record changes and deleted records](https://tadabase.com/docs/data/record-logs).

## Control equations when you save

By default a create or update recalculates the record's equations before the API answers. These request headers change that:

| Header | Effect |
| --- | --- |
| `X-Tadabase-Update-Equation: 0` | Saves the record without recalculating its equations. |
| `X-Tadabase-Table-Rules: 0` | Only with `X-Tadabase-Update-Equation: 0`: also skips the table's legacy rules. |
| `X-Tadabase-Queue-Equation: 1` | Answers as soon as the record is saved; the equations are recalculated in the background, so their values can lag behind. |
| `X-Tadabase-Update-Table-Equation: 1` | Also recalculates the equations of every record in the table, in the background. |

When you skip equations during a large load, recalculate them afterwards. See [Recalculate equations through the API](https://tadabase.com/docs/developers/formulas-and-equations).

## Record logs

If **Log Record Changes** is on in the table's **Record Tracking** settings, records you create and update through the API are logged like changes made in the app, with the API as the source.

## Errors

| Status | When |
| --- | --- |
| 400 | The save was refused. `msg` says why, for example "No Fields Supplied to be Saved.", an invalid email, or a value that must be unique. |
| 404 | Delete only: the record does not exist. |
| 409 | The save collided with a value that must be unique. |
| 412 | The API key does not have the permission this call needs, or the plan does not include API access. |
| 429 | Too many requests. See [API rate limits](https://tadabase.com/docs/developers/rate-limiting). |
