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.

Table of Contents

1. Getting Started
2. Authentication
3. Rate Limiting
4. API Request Tracking
5. Data Operations
6. User Authentication (v1.1)
7. Tables & Fields
8. Tasks API
9. Automations API
10. Webhooks API
11. Formulas & Equations
12. Imports & Exports
13. PDF Generation
14. Pages & Components (v1.1)
15. Field Types & Formats
16. Advanced Features
17. Error Handling
18. 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:

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

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:

1. Use the User Login endpoint to authenticate
2. Receive a token in the response
3. 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:

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

---

4. API Request Tracking

Overview

Tadabase automatically tracks all API requests made to your application, providing detailed logs for monitoring, debugging, and analytics purposes. This feature helps you understand API usage patterns, troubleshoot issues, and monitor performance.

Enabling API Request Tracking

To enable API request tracking, you need to configure two settings:

1. Enable at App Level

API request logging must be enabled for your application. This setting controls whether requests are tracked and stored.

2. Enable on API Key

Each API key can be configured with the allow_log permission. This controls whether requests made with that specific API key are logged.

To configure API key permissions:

1. Navigate to Settings > API Keys in the Builder
2. Edit your API key
3. Enable the Allow Logs permission
4. Save your changes

Information Tracked

Each API request logs the following information:

Field	Description
method	HTTP method used (GET, POST, PUT, DELETE)
url	Full request URL including query parameters
ip	IP address of the requesting client
headers	Request headers (serialized)
request	Request body/parameters (JSON format)
response	API response content
duration	Request processing time in seconds
created_at	Timestamp when request was made
platform	Operating system (Windows, Mac, Linux, etc.)
browser	Browser name and version
device_type	Device category (desktop, phone, robot)
device	Specific device name if available

Viewing API Request Logs

API request logs can be viewed directly in the Tadabase Builder:

1. Open your app in the Builder
2. Navigate to Settings > Logs
3. Select API Logs from the log type dropdown
4. View and filter your API request logs

Filtering Logs

You can filter API logs by date range to narrow down your search:

• From Date: Show logs from this date forward
• To Date: Show logs up to this date
• Date Range: Combine both to view logs within a specific timeframe

Limitations and Considerations

Plan Restrictions

API request tracking availability depends on your subscription plan:

• Not all plans include API request logging
• Contact support to verify if your plan includes this feature
• Consider upgrading your plan if API logging is required for your use case

Performance Impact

While tracking is optimized for minimal impact:

• Each logged request adds a small amount of processing overhead
• Large request/response payloads will require more storage
• Consider the storage implications for high-volume API usage

Data Retention

Important notes about log retention:

• Logs are stored in your app's database
• No automatic deletion or rotation policy is enforced by default
• You may need to periodically clean up old logs to manage storage
• Consider your compliance requirements for log retention

Sensitive Data

Common Use Cases

Debugging API Integrations

API logs are invaluable for troubleshooting:

• View exact request parameters sent by external systems
• Inspect response data to identify formatting issues
• Identify timing issues with request duration data
• Track down intermittent failures by reviewing historical requests

Monitoring and Analytics

Track API usage patterns:

• Identify most frequently accessed endpoints
• Monitor performance trends over time
• Detect unusual traffic patterns or potential security issues
• Analyze geographic distribution of API consumers

Audit Trail

Maintain compliance with audit requirements:

• Track who accessed your API and when
• Document data modifications made via API
• Provide evidence for security or compliance audits
• Investigate unauthorized access attempts

Best Practices

1. Enable Selectively: Only enable logging on API keys that require it to minimize storage overhead
2. Regular Review: Periodically review logs to identify optimization opportunities
3. Set Up Alerts: Monitor for error patterns or unusual activity
4. Archive Old Logs: Export and archive historical logs before deletion
5. Document Usage: Keep records of why certain API keys have logging enabled
6. Test Thoroughly: Verify logging works as expected in development before production use

---

5. 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. You can use either GET or POST methods:

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

Content-Type: application/json

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

Filter Operators

The following operators are supported for filtering records. Use the operator key in your filter items:

Text Field Operators

Operator	Description	Example
is	Exact match (case insensitive)	"operator": "is", "val": "Active"
is exact	Exact match (case sensitive)	"operator": "is exact", "val": "Active"
is not	Not equal (case insensitive)	"operator": "is not", "val": "Inactive"
is not exact	Not equal (case sensitive)	"operator": "is not exact", "val": "Inactive"
contains	Substring match	"operator": "contains", "val": "keyword"
does not contain	Does not contain substring	"operator": "does not contain", "val": "keyword"
starts with	Starts with value	"operator": "starts with", "val": "prefix"
ends with	Ends with value	"operator": "ends with", "val": "suffix"
is blank	Field is empty or NULL	"operator": "is blank"
is not blank	Field has a value	"operator": "is not blank"

Numeric and Date Field Operators

Operator	Description	Example
is	Equal to	"operator": "is", "val": 100
is not	Not equal to	"operator": "is not", "val": 100
>	Greater than	"operator": ">", "val": 100
>=	Greater than or equal to	"operator": ">=", "val": 100
<	Less than	"operator": "<", "val": 50
<=	Less than or equal to	"operator": "<=", "val": 50
between	Between two values (inclusive)	"operator": "between", "val": 10, "val2": 100
is blank	Field is empty or NULL	"operator": "is blank"
is not blank	Field has a value	"operator": "is not blank"

Boolean and Checkbox Operators

Operator	Description	Example
is checked	Checkbox is checked	"operator": "is checked"
is unchecked	Checkbox is unchecked	"operator": "is unchecked"

User and Authentication Operators

Operator	Description	Example
is logged in user	Matches currently authenticated user	"operator": "is logged in user"
is not logged in user	Does not match authenticated user	"operator": "is not logged in user"
is connected to logged in user	For join fields, checks connection to user	"operator": "is connected to logged in user"
is not connected to logged in user	For join fields, checks no connection to user	"operator": "is not connected to logged in user"

Join (Connection) Field Operators

Operator	Description	Example
is	Record is connected to specified ID	"operator": "is", "val": "record_id"
is not	Record is not connected to specified ID	"operator": "is not", "val": "record_id"
contains	Contains specific value in joined field	"operator": "contains", "val": "search"
is blank	No connections exist	"operator": "is blank"
is not blank	Has at least one connection	"operator": "is not blank"
is connected with current record	Connected to current page record	"operator": "is connected with current record"
is connected with current record's field	Connected via specific field	"operator": "is connected with current record's field"

Nested Filter Groups

You can create complex filters with nested groups using the child array. Each child group can have its own condition (AND/OR) and items:

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "is",
        "val": "Active"
      }
    ],
    "child": [
      {
        "condition": "any",
        "items": [
          {
            "field_id": "email",
            "operator": "contains",
            "val": "@example.com"
          },
          {
            "field_id": "email",
            "operator": "contains",
            "val": "@test.com"
          }
        ]
      }
    ]
  }
}

This example returns records where status is "Active" AND (email contains "@example.com" OR email contains "@test.com").

Important: Field Validation Behavior

Field Identifiers

The field_id parameter accepts either:

• Field IDs: The internal field ID like field_40
• Field Slugs: The slug name assigned to the field

For complex field types (Name, Address), you can reference sub-fields using a hyphen:

{
  "field_id": "full_name-first",
  "operator": "contains",
  "val": "John"
}

Debugging Filter Issues

If your filters aren't working as expected:

1. Use the GET /api/v1/data-tables/{dataTableId}/fields endpoint to verify field IDs
2. Check that you're using operator (not condition) in filter items
3. Check that you're using val (not value) for filter values
4. Ensure the field actually exists in the data table
5. Verify you're using the field ID or slug, not the display name
6. Test with a simple single-filter query first before adding complexity

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:

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

Content-Type: application/json

{
  "filters": {
    "condition": "AND",
    "items": [
      {
        "field_id": "status",
        "operator": "=",
        "val": "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": [
    {
      "condition": "AND",
      "items": [
        {
          "field_id": "status",
          "operator": "=",
          "val": "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"
}

---

6. User Authentication (API v1.1)

User Login

Authenticate a user and receive a bearer token for authenticated API requests:

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

Content-Type: application/json

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

Response:

{
  "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"
}

Auto Login

Login using email only (requires special configuration):

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=..."
}

---

7. 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
}

---

8. 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}

---

9. 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}

---

10. Webhooks API

Coming Soon.

---

11. 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
    }
  ]
}

---

12. 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": {
    "condition": "AND",
    "items": [
      {
        "field_id": "field_slug",
        "operator": "is",
        "val": "value"
      }
    ]
  },
  "columns": ["field_slug1", "field_slug2"]
}

The filters parameter is optional and follows the same structure as described in the Advanced Filtering section above.

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://..."
    }
  ]
}

---

13. 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}

---

14. 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={...}  (See Advanced Filtering section)
  sort_by=[...]

Filters can be passed as query parameters or via POST with JSON body. See the Advanced Filtering section for complete filter syntax.

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",
  ...
}

---

15. 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]

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"
    }
  ]
}

Important: Default Values and the API

Field default values configured in the Data Builder (such as Default Form Value for Decision Boxes, default dates, default select options, etc.) are only applied when records are created through forms in the application UI.

When creating records via the API, these defaults are NOT automatically applied. You must explicitly include each field and its value in your API request payload.

Field Behavior When Omitted from API Requests

Fields omitted from API requests will be set to empty/null values based on the field type:

Field Type	Value When Omitted	Example
Decision Box	0 (unchecked)	Even if Default Form Value is set to checked, API will set to 0
Select/Radio/Dropdown	Empty string	No option selected, regardless of default
Text fields	Empty string	""
Number fields	0 or null	Depends on field configuration
Date/Time fields	null	No date set
Checkbox (multi-select)	Empty array	[]

Best Practice: Always Specify Required Fields

When creating records via API, explicitly include all fields that should have values, even if they have default values configured in the Data Builder. This design gives API developers explicit control over exactly what data is being created.

Example with Decision Box:

POST /api/v1/data-tables/{dataTableId}/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:
{
  "field_132": 1,  // Explicitly set to checked
  "name": "John Doe",
  "email": "john@example.com"
}

// If field_132 is omitted, it will be set to 0 (unchecked)
// regardless of the Default Form Value setting

---

16. 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

---

17. 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)
  }
}

---

18. Best Practices

Security

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

Performance

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

Data Integrity

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

Monitoring & Logging

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

Development Workflow

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

API Versioning

1. Stay Current: Use the latest API version for new integrations
2. Test Before Migrating: When a new version is released, test thoroughly before migrating
3. 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.

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