Updated Rest API

Tadabase REST API Documentation

This comprehensive guide provides complete documentation for the Tadabase REST API, allowing you to programmatically interact with your Tadabase applications.

API Versions

Tadabase supports multiple API versions:

API v1.0: Core data operations (base URL: https://api.tadabase.io/api/v1)
API v1.1: Enhanced features including authentication, pages, and components (base URL: https://api.tadabase.io/api/v1.1/{appId})

Getting Started
Authentication
Rate Limiting
Data Operations
User Authentication (v1.1)
Tables & Fields
Tasks API
Automations API
Webhooks API
Formulas & Equations
Imports & Exports
PDF Generation
Pages & Components (v1.1)
Field Types & Formats
Advanced Features
Error Handling
Best Practices

1. Getting Started

Base URLs

API v1.0: https://api.tadabase.io/api/v1
API v1.1: https://api.tadabase.io/api/v1.1/{appId}

Generating API Keys

To use the Tadabase REST API, you must first generate an API key for your application:

Open your app in the Tadabase Builder
Navigate to Settings > API Keys
Click Generate New API Key
Copy the App ID, App Key, and App Secret

Important

Store your API credentials securely. The App Secret is shown only once when generated. If lost, you'll need to generate a new API key.

Required Headers

Every API request must include these three headers:

Header	Value	Description
`X-Tadabase-App-id`	Your App ID	Found in API Keys page or app URL
`X-Tadabase-App-Key`	Your App Key	Generated when creating API key
`X-Tadabase-App-Secret`	Your App Secret	Generated when creating API key

Check API Status

Verify your API credentials and check current rate limit status:

GET https://api.tadabase.io/api/v1/status

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

Response:

{
  "current_code": 200,
  "per_minute_limit": {
    "allowed": 120,
    "remaining": 118,
    "resets_in_seconds": 55,
    "reset_timestamp": 1704528000
  },
  "per_day_limit": {
    "allowed": 10000,
    "remaining": 9850,
    "resets_in_seconds": 38226,
    "reset_timestamp": 1704612000
  }
}

2. Authentication

API Key Authentication

API key authentication is required for all API requests. Include the three headers mentioned above with every request.

Bearer Token Authentication

For user-specific operations, you can authenticate as a specific user using a Bearer token. This is useful for operations that require user context, such as accessing records based on user permissions.

To obtain a Bearer token:

Use the User Login endpoint to authenticate
Receive a token in the response
Include the token in subsequent requests using the Authorization header

Authorization: Bearer {your_token_here}

API Key Permissions

API keys can be configured with specific permissions to control what operations they can perform:

Permission	Controls
`allow_get`	Read records (GET requests)
`allow_edit`	Create and update records (POST/PUT)
`allow_delete`	Delete records (DELETE)
`allow_task`	Execute tasks via API
`allow_export`	Trigger exports
`allow_import`	Trigger imports
`allow_log`	Access activity logs
`allow_page`	Access page components (v1.1)

3. Rate Limiting

Overview

Tadabase enforces rate limits to ensure fair usage and system stability. Rate limits are based on your subscription plan and are tracked at two levels:

Per Minute Limit: Maximum requests per minute
Per Day Limit: Maximum requests per day

Rate Limit Response Headers

Every API response includes headers showing your current rate limit status:

Per Minute Headers

Header	Description
`X-RateLimit-Limit`	Total allowed requests per minute
`X-RateLimit-Remaining`	Remaining requests for current minute
`X-Retry-After`	Seconds until the minute resets
`X-RateLimit-Reset`	Unix timestamp when minute resets

Per Day Headers

Header	Description
`X-RateLimit-Daily-Limit`	Total allowed requests per day
`X-RateLimit-Daily-Remaining`	Remaining requests for current day
`X-Daily-Retry-After`	Seconds until the day resets
`X-Daily-RateLimit-Reset`	Unix timestamp when day resets

Handling Rate Limits

When you exceed a rate limit, the API returns a 429 Too Many Requests status code. Your application should:

Monitor the rate limit headers in responses
Implement exponential backoff when approaching limits
Wait for the time specified in X-Retry-After before retrying
Consider upgrading your subscription plan if you consistently hit limits

Pro Tip

Check the X-RateLimit-Remaining header before making additional requests. If it's low, implement a delay or queue requests to avoid hitting the limit.

4. Data Operations

List Records

Retrieve a list of records from a data table with optional filtering, sorting, and pagination.

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

Query Parameters:
  page=1                    - Page number (default: 1)
  limit=100                 - Records per page (default: 100, max: 200)
  columns=field_slug1,field_slug2  - Specific fields to return
  fields=field_slug1,field_slug2   - Alternative to columns
  order=field_slug          - Sort by field
  order_by=asc              - Sort direction (asc/desc)
  display_names=true        - Use field names instead of slugs in response

Response:

{
  "type": "success",
  "items": [
    {
      "id": "encoded_record_id",
      "field_slug1": "value1",
      "field_slug2": "value2",
      "created_at": "2024-01-14 10:30:00"
    }
  ],
  "total_items": 150,
  "total_pages": 2,
  "current_page": 1,
  "limit": 100
}

Advanced Filtering

Apply complex filters to your record queries using the filters parameter:

POST /api/v1/data-tables/{dataTableId}/records?_zmode=search

Content-Type: application/json

{
  "filters": {
    "items": [
      {
        "field_id": "field_slug",
        "condition": "=",
        "value": "search_value"
      },
      {
        "field_id": "another_field",
        "condition": ">",
        "value": 100
      }
    ]
  },
  "page": 1,
  "limit": 50
}

Filter Operators

Operator	Description	Example
`=`	Equals	`"condition": "=", "value": "Active"`
`!=`	Not equals	`"condition": "!=", "value": "Inactive"`
`>`	Greater than	`"condition": ">", "value": 100`
`<`	Less than	`"condition": "<", "value": 50`
`>=`	Greater than or equal	`"condition": ">=", "value": 100`
`<=`	Less than or equal	`"condition": "<=", "value": 50`
`contains`	Contains text	`"condition": "contains", "value": "keyword"`
`startswith`	Starts with	`"condition": "startswith", "value": "prefix"`
`is_blank`	Field is empty	`"condition": "is_blank"`
`not_blank`	Field is not empty	`"condition": "not_blank"`

Sorting Records

Sort records by one or multiple fields:

GET /api/v1/data-tables/{dataTableId}/records?order=last_name&order_by=asc

Or with multiple sorts (POST with JSON):
{
  "sort_by": [
    {"sort": "status", "by": "desc"},
    {"sort": "created_at", "by": "asc"}
  ]
}

Get Single Record

Retrieve a specific record by its ID:

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

Query Parameters:
  columns=field1,field2    - Optional: specific fields only
  display_names=true       - Use field names instead of slugs

Response:

{
  "type": "success",
  "item": {
    "id": "encoded_record_id",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "created_at": "2024-01-14 10:30:00"
  }
}

Create Record

Create a new record in a data table:

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

Content-Type: multipart/form-data or application/json

Body:
{
  "field_slug1": "value1",
  "field_slug2": "value2"
}

Response:

{
  "type": "success",
  "msg": "Record saved successfully",
  "item": {
    "id": "encoded_record_id",
    "field_slug1": "value1",
    "field_slug2": "value2",
    "created_at": "2024-01-14 10:30:00"
  }
}

Update Record

Update an existing record:

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

Content-Type: multipart/form-data or application/json

Body:
{
  "field_slug1": "updated_value",
  "field_slug2": "updated_value2"
}

Delete Record

Delete a record from a data table:

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

Response:

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

Batch Operations

Check Batch Update Count

Check how many records will be affected by a batch update before executing it:

GET /api/v1/data-tables/{dataTableId}/records/batch-update-check

Content-Type: application/json

{
  "filters": {
    "items": [
      {
        "field_id": "status",
        "condition": "=",
        "value": "pending"
      }
    ]
  }
}

Response:

{
  "type": "success",
  "total": 45,
  "msg": "45 records will be updated"
}

Execute Batch Update

Update multiple records at once based on filter conditions:

POST /api/v1/data-tables/{dataTableId}/records/batch-update

Content-Type: application/json

{
  "conditions": [
    {
      "items": [
        {
          "field_id": "status",
          "condition": "=",
          "value": "pending"
        }
      ]
    }
  ],
  "values": [
    {
      "field_id": "status",
      "value": "approved",
      "val_type": "normal"
    },
    {
      "field_id": "approved_date",
      "value": "2024-01-14",
      "val_type": "normal"
    }
  ]
}

Response:

{
  "type": "success",
  "total": 45,
  "msg": "45 records updated successfully"
}

Important

Batch operations can affect many records at once. Always use the batch-update-check endpoint first to verify the number of records that will be updated.

5. User Authentication (API v1.1)

POST /api/v1.1/{appId}/auth/login

Content-Type: application/json

{
  "email": "user@example.com",
  "password": "user_password",
  "remember": false
}

{
  "type": "success",
  "token": "encrypted_bearer_token",
  "user_id": "encoded_user_id",
  "expires_at": "2024-01-21 10:30:00",
  "logged_in_since": "2024-01-14 10:30:00"
}

User Logout

Invalidate a user's bearer token:

POST /api/v1.1/{appId}/auth/logout

Authorization: Bearer {token}

Check Token Status

Verify if a bearer token is still valid:

POST /api/v1.1/{appId}/auth/status

Authorization: Bearer {token}

Response:

{
  "type": "success",
  "valid": true,
  "expires_at": "2024-01-21 10:30:00",
  "time_remaining": "6 days 23 hours"
}

POST /api/v1.1/{appId}/auth/auto-login

Content-Type: application/json

{
  "email": "user@example.com"
}

Magic Link

Generate a passwordless login link for a user:

POST /api/v1.1/{appId}/auth/magic-link

Content-Type: application/json

{
  "email": "user@example.com",
  "user_id": "encoded_user_id",
  "redirect_url": "https://example.com/dashboard",
  "redirect_page_id": "encoded_page_id"
}

Response:

{
  "type": "success",
  "token": "encrypted_token",
  "magicLinkUrl": "https://yourapp.tadabase.io/magic-link?token=..."
}

Note

Magic link functionality requires specific API key configuration. Contact support if you need this feature enabled.

6. Tables & Fields

List All Tables

Get a list of all data tables in your application:

GET /api/v1/data-tables

Response:

{
  "type": "success",
  "data_tables": [
    {
      "id": "encoded_table_id",
      "name": "Customers"
    },
    {
      "id": "encoded_table_id_2",
      "name": "Orders"
    }
  ],
  "total_items": 2
}

List Table Fields

Get basic field information for a specific table:

GET /api/v1/data-tables/{dataTableId}/fields

Response:

{
  "type": "success",
  "fields": [
    {
      "slug": "first_name",
      "name": "First Name",
      "type": "Text"
    },
    {
      "slug": "email",
      "name": "Email",
      "type": "Email"
    },
    {
      "slug": "status",
      "name": "Status",
      "type": "Select"
    }
  ],
  "total_items": 3
}

Get Full Field Information

Get detailed field metadata including options, validation rules, and relationships:

GET /api/v1/data-tables/{dataTableId}/full-fields-info

Response:

{
  "fields": [
    {
      "slug": "status",
      "fieldId": "encoded_field_id",
      "name": "Status",
      "type": "Select",
      "description": "Customer status",
      "default_value": "pending",
      "is_unique": "No",
      "options": [
        {"label": "Pending", "value": "pending"},
        {"label": "Active", "value": "active"},
        {"label": "Inactive", "value": "inactive"}
      ]
    },
    {
      "slug": "assigned_to",
      "fieldId": "encoded_field_id_2",
      "name": "Assigned To",
      "type": "Connection",
      "join": {
        "join_type": "1-to-N",
        "data_table_id": "encoded_users_table_id",
        "field_slug": "full_name",
        "field_id": "encoded_field_id"
      }
    }
  ]
}

List Roles

Get all user roles configured in your application:

GET /api/v1/roles

Response:

{
  "type": "success",
  "items": [
    {
      "id": "encoded_role_id",
      "name": "Admin",
      "description": "Administrator role",
      "enable_stripe": "Yes"
    },
    {
      "id": "encoded_role_id_2",
      "name": "User",
      "description": "Standard user role",
      "enable_stripe": "No"
    }
  ],
  "total_items": 2
}

7. Tasks API

List All Tasks

Get all tasks configured in your application:

GET /api/v1/tasks

Response:

{
  "type": "success",
  "total_tasks": 3,
  "tasks": [
    {
      "task_id": "encoded_task_id",
      "name": "Daily Email Send",
      "status": "Active",
      "data_table_id": "encoded_table_id",
      "occurrence": "Daily",
      "next_run_at": "2024-01-15 10:00:00",
      "type": "Schedule"
    }
  ]
}

Run Task

Trigger immediate execution of a task:

POST /api/v1/tasks/run/{taskId}

Response:

{
  "type": "success",
  "task_queue_id": "encoded_queue_id",
  "msg": "Task started successfully"
}

Check Task Status

Monitor the progress of task executions:

All Active Tasks

GET /api/v1/tasks/status

Specific Task Queue

GET /api/v1/tasks/status/queue/{taskQueueId}

All Executions of a Task

GET /api/v1/tasks/status/task/{taskId}

Response:

{
  "type": "success",
  "total_tasks": 1,
  "tasks": [
    {
      "task_queue_id": "encoded_queue_id",
      "task_id": "encoded_task_id",
      "total_records": 500,
      "total_record_proceed": 450,
      "start_at": "2024-01-14 08:30:00",
      "run_type": "API",
      "status": "start"
    }
  ]
}

Task History

Get completed task executions:

GET /api/v1/tasks/history

Terminate Task

Stop a running task execution:

POST /api/v1/tasks/terminate/queue/{taskQueueId}

Or terminate all executions of a task:

POST /api/v1/tasks/terminate/task/{taskId}

8. Automations API

The Automations API follows the same pattern as the Tasks API but for automation workflows.

Run Automation

POST /api/v1/automations/run/{automationId}

Status Endpoints

GET /api/v1/automations/status
GET /api/v1/automations/status/queue/{automationQueueId}
GET /api/v1/automations/status/automation/{automationId}
GET /api/v1/automations/history

Terminate Automation

POST /api/v1/automations/terminate/queue/{automationQueueId}
POST /api/v1/automations/terminate/automation/{automationId}

9. Webhooks API

POST /api/v1/web-hooks/subscribe

Content-Type: application/json

{
  "data_table_id": "encoded_table_id",
  "type": "INSERT",
  "hookUrl": "https://your-webhook.example.com/endpoint",
  "platform": "Custom"
}

Available webhook types:

INSERT - Triggered when a new record is created
UPDATE - Triggered when a record is updated
DELETE - Triggered when a record is deleted

{
  "type": "success",
  "id": "encoded_webhook_id",
  "msg": "Webhook subscribed successfully"
}

List Webhooks

GET /api/v1/web-hooks/list?data_table_id={tableId}

Unsubscribe Webhook

DELETE /api/v1/web-hooks/unsubscribe

Content-Type: application/json

{
  "id": "encoded_webhook_id"
}

Webhook Payload

When a webhook is triggered, Tadabase sends a POST request to your webhook URL with the following payload:

{
  "event_type": "INSERT",
  "table_id": "encoded_table_id",
  "table_name": "Customers",
  "record": {
    "id": "encoded_record_id",
    "field_slug1": "value1",
    "field_slug2": "value2",
    "created_at": "2024-01-14 10:30:00"
  },
  "timestamp": "2024-01-14T10:30:00Z"
}

10. Formulas & Equations

Overview

Formula and equation fields in Tadabase can be recalculated via the API. This is useful when you've made bulk changes and need to update calculated values.

Update All Formulas (Entire App)

POST /api/v1/update-all-formula

Update All Formulas (Specific Table)

POST /api/v1/update-all-formula/{dataTableId}

Update Specific Formula Field

By Field Slug

POST /api/v1/update-field-formula-by-slug/{fieldSlug}

Or force recalculation:

POST /api/v1/update-field-formula-by-slug/{fieldSlug}/force

By Field ID

POST /api/v1/update-field-formula-by-id/{fieldId}

Or force recalculation:

POST /api/v1/update-field-formula-by-id/{fieldId}/force

Formula Execution Control Headers

When creating or updating records, you can control formula execution with these 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

Get Formula Execution Log

View detailed logs of formula execution by adding a query parameter:

POST /api/v1/data-tables/{dataTableId}/records?showequationlog=true

Body: {record data}

Response includes:

{
  "type": "success",
  "item": {...},
  "equationLog": [
    {
      "field": "total_price",
      "formula": "quantity * unit_price",
      "result": 150.00,
      "execution_time_ms": 2
    }
  ]
}

Performance Tip

For bulk operations, consider queuing formula execution (X-Tadabase-Queue-Equation: 1) to improve response times. Formulas will be calculated asynchronously in the background.

11. Imports & Exports (API v1.1)

Imports

List Import Templates

GET /api/v1.1/{appId}/imports

Query Parameters:
  limit=10
  page=1
  dataTableId={tableId}  (optional filter)

Get Import Template Details

GET /api/v1.1/{appId}/imports/{importId}

Trigger Import

POST /api/v1.1/{appId}/imports/{importId}/trigger

Content-Type: multipart/form-data

Body: {file upload or data source}

Check Import Status

GET /api/v1.1/{appId}/imports/queues
GET /api/v1.1/{appId}/imports/queues/{queueId}
GET /api/v1.1/{appId}/imports/status/{queueId}

Response:

{
  "type": "success",
  "items": [
    {
      "id": "encoded_queue_id",
      "status": "Processing",
      "total_rows": 1000,
      "processed_rows": 850,
      "error_rows": 10,
      "created_at": "2024-01-14 10:00:00"
    }
  ]
}

Exports

List Export Templates

GET /api/v1.1/{appId}/exports
GET /api/v1.1/{appId}/exports/templates

Get Export Template Details

GET /api/v1.1/{appId}/exports/templates/{templateId}

Trigger Export

POST /api/v1.1/{appId}/exports/templates/{templateId}/trigger

Content-Type: application/json

{
  "filters": {...},  (optional record filters)
  "columns": ["field_slug1", "field_slug2"]  (optional)
}

Check Export Status

GET /api/v1.1/{appId}/exports/queues
GET /api/v1.1/{appId}/exports/queues/{queueId}

Response:

{
  "type": "success",
  "items": [
    {
      "id": "encoded_export_id",
      "dataTable": {
        "id": "encoded_table_id",
        "name": "Customers"
      },
      "exportTemplate": {
        "id": "encoded_template_id",
        "name": "CSV Export"
      },
      "status": "Complete",
      "complete": 500,
      "start_date": "2024-01-14 10:00:00",
      "end_date": "2024-01-14 10:05:00",
      "download_url": "https://..."
    }
  ]
}

12. PDF Generation (API v1.1)

PDF Pages

List PDF Page Templates

GET /api/v1.1/{appId}/pdf-pages

Get PDF Page Template

GET /api/v1.1/{appId}/pdf-pages/{pdfPageId}

Generate PDF from Record

POST /api/v1.1/{appId}/pdf-pages/{pdfPageId}/create/{recordId}

PDF Forms

List PDF Form Templates

GET /api/v1.1/{appId}/pdf-forms

Get PDF Form Template

GET /api/v1.1/{appId}/pdf-forms/{pdfFormId}

Generate PDF Form

POST /api/v1.1/{appId}/pdf-forms/{pdfFormId}/create

Content-Type: application/json

{record data for PDF}

13. Pages & Components (API v1.1)

Layouts

GET /api/v1.1/{appId}/layouts

Pages

List All Pages

GET /api/v1.1/{appId}/pages

Response:

{
  "status": "success",
  "items": [
    {
      "id": "encoded_page_id",
      "name": "Home",
      "slug": "home",
      "status": "Active",
      "layout_id": "encoded_layout_id",
      "is_secure": 0,
      "total_child_pages": 2
    }
  ]
}

Get Child Pages

GET /api/v1.1/{appId}/pages/{pageId}/childs
GET /api/v1.1/{appId}/pages/{pageId}/childs/{childIds}

Get Page Components

GET /api/v1.1/{appId}/pages/{pageId}/components

Get Component Records

GET /api/v1.1/{appId}/pages/{pageId}/components/{componentId}/records

Query Parameters:
  page=1
  limit=50
  filters={...}
  sort_by=[...]

Get Component Details

GET /api/v1.1/{appId}/pages/{pageId}/components/{componentId}/details

Save Record from Component

POST /api/v1.1/{appId}/pages/{pageId}/components/{componentId}/save

Content-Type: application/json

{
  "id": "encoded_record_id",  (for update)
  "field_slug": "value",
  ...
}

14. Field Types & Formats

Different field types require specific data formats when creating or updating records. Here's a comprehensive guide:

Simple Field Types

Field Type	Format	Example
Text	String	`"field_slug": "Hello World"`
Email	String (email format)	`"email": "user@example.com"`
Phone	String	`"phone": "555-123-4567"`
Number	Integer or Float	`"quantity": 42` or `"price": 19.99`
Currency	Float	`"amount": 1234.56`
Decision Box	Boolean (0 or 1)	`"is_active": 1`
Long Text	String	`"description": "Long text..."`
Rich Text	HTML String	`"content": "<p>HTML content</p>"`

Date and Time Fields

Field Type	Format	Example
Date	YYYY-MM-DD	`"date_field": "2024-01-14"`
Time	HH:MM:SS	`"time_field": "14:30:00"`
Date-Time	YYYY-MM-DD HH:MM:SS	`"datetime_field": "2024-01-14 14:30:00"`

Calendar (Date Range)

{
  "event_date__start": "2024-01-14",
  "event_date__end": "2024-01-20"
}

Name Field

Name fields consist of multiple sub-fields that must be specified individually:

{
  "full_name[title]": "Mr.",
  "full_name[first_name]": "John",
  "full_name[middle_name]": "C",
  "full_name[last_name]": "Doe"
}

Address Field

Address fields have multiple components:

{
  "address[address]": "123 Main Street",
  "address[address2]": "Apt 4B",
  "address[city]": "New York",
  "address[state]": "NY",
  "address[zip]": "10001",
  "address[country]": "USA"
}

Select & Radio (Single Choice)

{
  "status": "active"
}

Multi-Select & Checkbox

{
  "interests": ["sports", "music", "travel"]
}

Or as form-data:
interests[]=sports&interests[]=music&interests[]=travel

Connection (Join) Fields

One-to-One Connection

{
  "assigned_to": "encoded_user_id"
}

One-to-Many Connection

{
  "team_members": ["encoded_user_id_1", "encoded_user_id_2", "encoded_user_id_3"]
}

Or comma-separated:
{
  "team_members": "encoded_user_id_1,encoded_user_id_2"
}

Or as form-data:
team_members[]=id1&team_members[]=id2

File Upload

Content-Type: multipart/form-data

file_field: [file upload]

Linked Record Creation

Create a record and automatically link it to another record:

{
  "field_slug1": "value1",
  "field_slug2": "value2",
  "connected_to": {
    "join_type": "joinTo",
    "field_id": "encoded_connection_field_id",
    "record_id": "encoded_parent_record_id"
  }
}

Reading Join Field Values

When retrieving records with join fields, the API returns both IDs and display values:

{
  "assigned_to": ["encoded_user_id"],
  "assigned_to_val": [
    {
      "id": "encoded_user_id",
      "val": "John Doe"
    }
  ]
}

15. Advanced Features

Caching

Tadabase implements intelligent caching to improve API performance:

Redis Caching

The API uses Redis to cache:

App configuration and metadata
Rate limiter state
User authentication tokens
Field metadata and options

Query Optimization

Advanced optimizations include:

Batch Loading: Join field data is loaded in batches to avoid N+1 queries
Pre-computed Totals: Record counts are calculated before pagination
Field Metadata Caching: Field configurations are cached per request

Pagination

All list endpoints support pagination with consistent parameters:

GET /api/v1/data-tables/{dataTableId}/records?page=2&limit=50

Response includes:
{
  "items": [...],
  "total_items": 500,
  "total_pages": 10,
  "current_page": 2,
  "limit": 50
}

Data Validation

The API enforces validation rules configured on your fields:

Required Fields: Returns error if required field is empty
Unique Constraints: Prevents duplicate values in unique fields
Data Type Validation: Ensures correct format for email, phone, number, date fields
Custom Validation: Enforces custom validation rules configured in table rules

Record Change Logging

When enabled on a table, all changes are automatically logged with:

User who made the change
Timestamp of change
Fields that were modified
Old and new values
Source of change (API, Builder, Page)

Bulk Operations

For large datasets, consider:

Batch Updates: Update multiple records with a single API call
Queued Formula Execution: Use X-Tadabase-Queue-Equation: 1 header to defer formula calculations
Import API: Use imports for bulk data loads
Rate Limit Management: Implement delays between requests to avoid hitting limits

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) with:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, X-Auth-Token, X-Tadabase-App-id,
                              X-Tadabase-App-Key, X-Tadabase-App-Secret

16. Error Handling

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
401	Unauthorized	Invalid API credentials
403	Forbidden	API key lacks required permissions
404	Not Found	Resource doesn't exist
412	Precondition Failed	Subscription limit or feature disabled
422	Validation Error	Invalid data or validation failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Error Response Format

{
  "type": "error",
  "msg": "Error description",
  "status": 422,
  "errors": {
    "field_slug": ["Validation error message"]
  }
}

Common Error Messages

Error	Cause	Solution
"API Not Found"	Invalid API key	Verify API key credentials
"APP Not Found"	Invalid app ID	Check app ID in API keys page
"API Disabled"	API key was disabled	Enable API key in builder
"Table Not Found"	Invalid table ID	List tables to get correct ID
"Record Not Found"	Record doesn't exist	Verify record ID is correct
"Too Many Attempts In Minute"	Per-minute rate limit exceeded	Wait and implement rate limiting
"Too Many Attempts In Day"	Per-day rate limit exceeded	Upgrade plan or wait 24 hours
"Permission Denied"	API key lacks permission	Update API key permissions
"Feature not available in your plan"	Subscription limit	Upgrade subscription plan
"This field is unique"	Duplicate value in unique field	Use a different value

Implementing Retry Logic

When implementing API calls, use exponential backoff for transient errors:

// Pseudo-code example
function makeApiRequest(url, data) {
  maxRetries = 3
  retryDelay = 1000  // Start with 1 second

  for (attempt = 1; attempt = 500) {
      // Server error - retry with exponential backoff
      wait(retryDelay * attempt + ' milliseconds')
      continue
    }

    // Other errors - don't retry
    throw error(response.msg)
  }
}

17. Best Practices

Security

Protect API Credentials: Never expose API keys in client-side code or public repositories
Use Environment Variables: Store credentials in environment variables, not in code
Regenerate Compromised Keys: If a key is exposed, immediately generate a new one
Use HTTPS: Always use HTTPS endpoints to encrypt data in transit
Implement IP Whitelisting: If possible, restrict API access to specific IP addresses
Least Privilege: Grant API keys only the permissions they need

Performance

Minimize Field Selection: Use the columns parameter to request only needed fields
Implement Pagination: Don't fetch all records at once - use pagination
Batch Operations: Use batch update instead of individual updates when possible
Queue Formula Execution: For bulk operations, queue formula calculations
Cache Responses: Cache API responses in your application when appropriate
Monitor Rate Limits: Track rate limit headers and implement throttling
Use Webhooks: Instead of polling, use webhooks for real-time updates

Data Integrity

Validate Before Sending: Validate data in your application before making API calls
Handle Errors Gracefully: Implement proper error handling and logging
Test in Sandbox: Test API integrations in a development/staging environment first
Verify Unique Constraints: Check for existing records before creating new ones
Use Transactions: For multi-step operations, verify each step before proceeding
Backup Before Bulk Operations: Consider backing up data before large bulk updates

Monitoring & Logging

Log API Requests: Maintain logs of all API calls for debugging
Monitor Rate Limits: Track rate limit consumption and set alerts
Track Errors: Log and monitor error responses
Performance Metrics: Monitor API response times
Alert on Failures: Set up alerts for repeated failures or rate limit hits

Development Workflow

Use Postman Collection: Import the Tadabase Postman collection for testing
Test with Small Datasets: Start with small record sets when testing
Document Your Integration: Maintain documentation of your API usage
Version Control: Keep API integration code in version control
Code Reviews: Have API integration code reviewed by team members

API Versioning

Stay Current: Use the latest API version for new integrations
Test Before Migrating: When a new version is released, test thoroughly before migrating
Monitor Deprecation Notices: Watch for announcements about deprecated endpoints

Summary

The Tadabase REST API provides comprehensive programmatic access to your applications. Key capabilities include:

Complete CRUD Operations: Create, read, update, and delete records
Advanced Filtering: Complex queries with multiple conditions and operators
User Authentication: Bearer token authentication for user-specific operations
Task & Automation Execution: Trigger and monitor background jobs
Webhooks: Real-time notifications for data changes
Formula Management: Recalculate equations and formulas programmatically
Import/Export: Bulk data operations
PDF Generation: Create PDFs from records and templates
Pages & Components: Access to page-level data and components
Rate Limiting: Fair usage enforcement with transparent limits

For additional support or questions about the API, please contact Tadabase support or visit our community forum.

Need Help?

This documentation covers all public-facing REST API endpoints. If you need assistance:

Review the examples and best practices
Test endpoints using the Postman collection
Check the error handling section for common issues
Contact Tadabase support with specific API questions

This documentation is regularly updated to reflect new features and improvements to the Tadabase REST API.

How did we do ?

Previous Section

Code Snippets

PHP Curl Create New Record

PHP Get Records With Filters

Google Scripts - Get record and create new records from connected table

Save Tables and Fields into Spreadsheet

Google Scripts - Export all records

Webhook to save deleted records

Send Messages to Slack

Restrict Space and Force Uppercase in a Form

Updated Rest API

Tadabase REST API Documentation

API Versions

Table of Contents

1. Getting Started

Base URLs

Generating API Keys

Important

Required Headers

Check API Status

2. Authentication

API Key Authentication

Bearer Token Authentication

API Key Permissions

3. Rate Limiting

Overview

Rate Limit Response Headers

Per Minute Headers

Per Day Headers

Handling Rate Limits

Pro Tip

4. Data Operations

List Records

Advanced Filtering

Filter Operators

Sorting Records

Get Single Record

Create Record

Update Record

Delete Record

Batch Operations

Check Batch Update Count

Execute Batch Update

Important

5. User Authentication (API v1.1)

User Login

User Logout

Check Token Status

Auto Login

Magic Link

Note

6. Tables & Fields

List All Tables

List Table Fields

Get Full Field Information

List Roles

7. Tasks API

List All Tasks

Run Task

Check Task Status

All Active Tasks

Specific Task Queue

All Executions of a Task

Task History

Terminate Task

8. Automations API

Run Automation

Status Endpoints

Terminate Automation

9. Webhooks API

Subscribe to Webhook

List Webhooks

Unsubscribe Webhook

Webhook Payload

10. Formulas & Equations

Overview

Update All Formulas (Entire App)

Update All Formulas (Specific Table)

Update Specific Formula Field

By Field Slug

By Field ID

Formula Execution Control Headers