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.
- Verified Nov 17, 2026
- Classic builder
On this page
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.
{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.
List records #
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" 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:
{
"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. |
order, order_by, sort_by | Sort the list. See Sort and page through records. |
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 shows how every field type comes back.
Get one record #
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" 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); {
"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.
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"}' 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(); {
"type": "success",
"recordId": "K2ejlOQo9B",
"msg": "The record has been successfully saved."
} - Add
?return=trueto the URL to get the saved record back inrecord. - 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 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.
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"}' 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 #
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" const res = await fetch(`${BASE}/data-tables/${tableId}/records/${recordId}`, { method: 'DELETE', headers });
const { type, msg } = await res.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.
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.
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. |
Was this page helpful?
Something wrong or missing on this page? Tell us.