Working With Records

Working with Records (CRUD Operations)

Learn how to create, read, update, and delete records in your Tadabase data tables using the REST API. These are the fundamental operations you'll use most frequently.

Overview of CRUD Operations

Operation	HTTP Method	Endpoint	Purpose
Create	POST	`/data-tables/{tableId}/records`	Create a new record
Read (List)	GET	`/data-tables/{tableId}/records`	Get multiple records
Read (Single)	GET	`/data-tables/{tableId}/records/{recordId}`	Get one specific record
Update	POST	`/data-tables/{tableId}/records/{recordId}`	Update an existing record
Delete	DELETE	`/data-tables/{tableId}/records/{recordId}`	Delete a record

Read: List Records

Retrieve a list of records from a data table.

Basic Request

GET /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "items": [
    {
      "id": "5e3f4a2b1c9d8e7f",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "status": "Active",
      "created_at": "2024-01-14 10:30:00"
    },
    {
      "id": "6f4g5b3c2d0e9f8g",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "status": "Active",
      "created_at": "2024-01-15 14:22:00"
    }
  ],
  "total_items": 150,
  "total_pages": 2,
  "current_page": 1,
  "limit": 100
}

Query Parameters

Parameter	Type	Description	Example
`page`	integer	Page number (default: 1)	`?page=2`
`limit`	integer	Records per page (default: 100, max: 200)	`?limit=50`
`fields`	string	Comma-separated field slugs to return	`?fields=first_name,email`
`columns`	array	Alternative to fields	`?columns=first_name,email`
`order`	string	Field to sort by	`?order=last_name`
`order_by`	string	Sort direction (asc/desc)	`?order_by=desc`
`display_names`	boolean	Use field names instead of slugs	`?display_names=true`

Example with Parameters

GET /api/v1/data-tables/lGArg7rmR6/records?page=1&limit=10&order=created_at&order_by=desc&fields=first_name,last_name,email

This returns the 10 most recently created records with only first_name, last_name, and email fields.

Read: Get Single Record

Retrieve a specific record by its ID.

Request

GET /api/v1/data-tables/{tableId}/records/{recordId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "item": {
    "id": "5e3f4a2b1c9d8e7f",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "Active",
    "phone": "555-123-4567",
    "created_at": "2024-01-14 10:30:00",
    "updated_at": "2024-01-20 09:15:00"
  }
}

Query Parameters

columns - Limit fields returned
display_names - Use field names instead of slugs

Create: Add New Record

Create a new record in a data table.

Request

POST /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Content-Type: application/json

Body:
{
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "alice@example.com",
  "status": "Active",
  "phone": "555-987-6543"
}

Response

{
  "type": "success",
  "msg": "Record saved successfully",
  "item": {
    "id": "7h5i6c4d3e1f0g9h",
    "first_name": "Alice",
    "last_name": "Johnson",
    "email": "alice@example.com",
    "status": "Active",
    "phone": "555-987-6543",
    "created_at": "2024-01-27 15:45:00"
  }
}

Content Types

You can submit data in two formats:

JSON (Recommended)

Content-Type: application/json

{
  "field_slug": "value"
}

Form Data (for file uploads)

Content-Type: multipart/form-data

field_slug=value
file_field=[file upload]

Important Notes

Default Values Not Applied

Default values configured in the Data Builder are NOT automatically applied when creating records via API. You must explicitly include all field values in your request.

For example, if a Decision Box has a default value of "checked" in the builder, you must still send "field_slug": 1 in your API request, or it will be set to 0 (unchecked).

Update: Modify Existing Record

Update an existing record by its ID.

Request

POST /api/v1/data-tables/{tableId}/records/{recordId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  Content-Type: application/json

Body:
{
  "status": "Inactive",
  "notes": "Account deactivated by user request"
}

Response

{
  "type": "success",
  "msg": "Record updated successfully",
  "item": {
    "id": "5e3f4a2b1c9d8e7f",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "Inactive",
    "notes": "Account deactivated by user request",
    "updated_at": "2024-01-27 16:20:00"
  }
}

Partial Updates

You only need to include the fields you want to update. Other fields remain unchanged:

{
  "status": "Active"
}

This updates only the status field, leaving all other fields untouched.

Delete: Remove Record

Delete a record from a data table.

Request

DELETE /api/v1/data-tables/{tableId}/records/{recordId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "msg": "Record deleted successfully"
}

⚠️ Deletion is Permanent

Deleted records cannot be recovered unless you have backups. Always verify the record ID before deleting. Consider using a "status" field (Active/Deleted) for soft deletes instead.

Formula and Equation Execution

When creating or updating records, you can control how formulas and equations are executed using special headers:

Header	Value	Description
`X-Tadabase-Queue-Equation`	`0` or `1`	Queue formula execution (async)
`X-Tadabase-Update-Equation`	`0` or `1`	Execute formulas immediately
`X-Tadabase-Table-Rules`	`0` or `1`	Run table rules
`X-Tadabase-Update-Table-Equation`	`0` or `1`	Update table-level equations

Example: Skip Formula Execution for Better Performance

POST /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  X-Tadabase-Queue-Equation: 1
  Content-Type: application/json

Body:
{
  "quantity": 10,
  "unit_price": 50.00
}

Setting X-Tadabase-Queue-Equation: 1 queues formula calculations for async processing, making the API response faster.

Complete Code Examples

JavaScript (Node.js)

const axios = require('axios');

const API_BASE = 'https://api.tadabase.io/api/v1';
const TABLE_ID = 'lGArg7rmR6';
const headers = {
  'X-Tadabase-App-id': 'your_app_id',
  'X-Tadabase-App-Key': 'your_app_key',
  'X-Tadabase-App-Secret': 'your_app_secret'
};

// Create
async function createRecord(data) {
  const response = await axios.post(
    `${API_BASE}/data-tables/${TABLE_ID}/records`,
    data,
    { headers }
  );
  console.log('Created:', response.data.item);
  return response.data.item;
}

// Read List
async function getRecords() {
  const response = await axios.get(
    `${API_BASE}/data-tables/${TABLE_ID}/records?limit=10`,
    { headers }
  );
  console.log('Records:', response.data.items);
  return response.data.items;
}

// Read Single
async function getRecord(recordId) {
  const response = await axios.get(
    `${API_BASE}/data-tables/${TABLE_ID}/records/${recordId}`,
    { headers }
  );
  console.log('Record:', response.data.item);
  return response.data.item;
}

// Update
async function updateRecord(recordId, data) {
  const response = await axios.post(
    `${API_BASE}/data-tables/${TABLE_ID}/records/${recordId}`,
    data,
    { headers }
  );
  console.log('Updated:', response.data.item);
  return response.data.item;
}

// Delete
async function deleteRecord(recordId) {
  const response = await axios.delete(
    `${API_BASE}/data-tables/${TABLE_ID}/records/${recordId}`,
    { headers }
  );
  console.log('Deleted:', response.data.msg);
  return response.data;
}

// Example usage
(async () => {
  // Create a new record
  const newRecord = await createRecord({
    first_name: 'Bob',
    last_name: 'Williams',
    email: 'bob@example.com'
  });

  // Update the record
  await updateRecord(newRecord.id, {
    status: 'Active'
  });

  // Get all records
  await getRecords();

  // Delete the record
  await deleteRecord(newRecord.id);
})();

Python

import requests
import json

API_BASE = "https://api.tadabase.io/api/v1"
TABLE_ID = "lGArg7rmR6"
headers = {
    "X-Tadabase-App-id": "your_app_id",
    "X-Tadabase-App-Key": "your_app_key",
    "X-Tadabase-App-Secret": "your_app_secret"
}

# Create
def create_record(data):
    url = f"{API_BASE}/data-tables/{TABLE_ID}/records"
    response = requests.post(url, json=data, headers=headers)
    return response.json()

# Read List
def get_records():
    url = f"{API_BASE}/data-tables/{TABLE_ID}/records?limit=10"
    response = requests.get(url, headers=headers)
    return response.json()

# Read Single
def get_record(record_id):
    url = f"{API_BASE}/data-tables/{TABLE_ID}/records/{record_id}"
    response = requests.get(url, headers=headers)
    return response.json()

# Update
def update_record(record_id, data):
    url = f"{API_BASE}/data-tables/{TABLE_ID}/records/{record_id}"
    response = requests.post(url, json=data, headers=headers)
    return response.json()

# Delete
def delete_record(record_id):
    url = f"{API_BASE}/data-tables/{TABLE_ID}/records/{record_id}"
    response = requests.delete(url, headers=headers)
    return response.json()

# Example usage
new_record = create_record({
    "first_name": "Bob",
    "last_name": "Williams",
    "email": "bob@example.com"
})

print("Created:", new_record)

Common Errors

422 Validation Error

{
  "type": "error",
  "msg": "Validation failed",
  "status": 422,
  "errors": {
    "email": ["Email is required"],
    "status": ["This field is unique"]
  }
}

Cause: Data doesn't meet validation rules
Solution: Check the errors object and fix the invalid fields

404 Record Not Found

{
  "type": "error",
  "msg": "Record Not Found",
  "status": 404
}

Cause: Invalid record ID
Solution: Verify the record exists and the ID is correct

Next Steps

Now that you understand basic CRUD operations, learn how to filter and search records:

→ Filtering Records - Simple and Advanced

Master filtering records with simple conditions and complex nested filters.

How did we do ?

Authentication Methods

Filtering Records

Working With Records

Working with Records (CRUD Operations)

Overview of CRUD Operations

Read: List Records

Basic Request

Response

Query Parameters

Example with Parameters

Read: Get Single Record

Request

Response

Query Parameters

Create: Add New Record

Request

Response

Content Types

JSON (Recommended)

Form Data (for file uploads)

Important Notes

Default Values Not Applied

Update: Modify Existing Record

Request

Response

Partial Updates

Delete: Remove Record

Request

Response

⚠️ Deletion is Permanent

Formula and Equation Execution

Example: Skip Formula Execution for Better Performance

Complete Code Examples

JavaScript (Node.js)

Python

Common Errors

422 Validation Error

404 Record Not Found

Next Steps

How did we do ?

We'd love to hear your feedback.