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
  1. The record endpoints
  2. List records
  3. Get one record
  4. Create a record
  5. Update a record
  6. Delete a record
  7. Control equations when you save
  8. Record logs
  9. Errors

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 #

ActionMethod and pathAPI key permission
List recordsGET /data-tables/{tableId}/recordsAllow Reads
Get one recordGET /data-tables/{tableId}/records/{recordId}Allow Reads
Create a recordPOST /data-tables/{tableId}/recordsAllow Updates
Update a recordPOST /data-tables/{tableId}/records/{recordId}Allow Updates
Delete a recordDELETE /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 #

Shell
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"
JavaScript
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 parameterWhat it does
pageThe page to return, starting at 1.
limitRecords per page. 100 is the most, and the default.
fieldsComma-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_names1 keys each value by the field's name instead of its slug.
filtersReturn only matching records. See Filter records in API requests.
order, order_by, sort_bySort 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 #

Shell
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"
JavaScript
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.

Shell
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"}'
JavaScript
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 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.

Shell
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"}'
JavaScript
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 #

Shell
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"
JavaScript
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.

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:

HeaderEffect
X-Tadabase-Update-Equation: 0Saves the record without recalculating its equations.
X-Tadabase-Table-Rules: 0Only with X-Tadabase-Update-Equation: 0: also skips the table's legacy rules.
X-Tadabase-Queue-Equation: 1Answers 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: 1Also 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 #

StatusWhen
400The save was refused. msg says why, for example "No Fields Supplied to be Saved.", an invalid email, or a value that must be unique.
404Delete only: the record does not exist.
409The save collided with a value that must be unique.
412The API key does not have the permission this call needs, or the plan does not include API access.
429Too many requests. See API rate limits.

Was this page helpful?

Something wrong or missing on this page? Tell us.