Read your tables, fields and roles

List an app's data tables, each table's fields with their types and options, and the app's user roles through the REST API.

  • Verified Nov 17, 2026
  • Classic builder
  • Available on: Business Starter, Business Growth, Business Pro, Business Elite

On this page
  1. Before you start
  2. List the tables
  3. List a table's fields
  4. Get full field details
  5. List the user roles
  6. Get the whole app schema in one call
  7. What to do with it
  8. Common problems

Before you read or write records, you need the IDs of your tables and the slugs of their fields. These endpoints return the app's structure: its tables, the fields in each table, and its user roles.

Before you start #

  • Your plan must include API access.
  • Every request sends the X-Tadabase-App-Id, X-Tadabase-App-Key and X-Tadabase-App-Secret headers. See Getting your API keys.
  • The API key needs Allow Reads turned on. Without it these endpoints answer 412 with "The method being used is disabled for this API key."
EndpointReturns
GET /api/v1/data-tablesEvery visible table: id and name
GET /api/v1/data-tables/{tableId}/fieldsThe table's fields: slug, name, type
GET /api/v1/data-tables/{tableId}/full-fields-infoThe table's fields with defaults, options and connection details
GET /api/v1/rolesThe app's user roles

List the tables #

Shell
curl https://api.tadabase.io/api/v1/data-tables \
  -H "X-Tadabase-App-Id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET"
JSON
{
  "data_tables": [
    { "id": "o6WQb5NnBZ", "name": "Customers" },
    { "id": "lGArg7rmR6", "name": "Jobs" }
  ],
  "total_items": 2,
  "type": "success"
}

Only tables that are visible in the builder are listed. Use the id in every record and field endpoint.

List a table's fields #

GET /api/v1/data-tables/{tableId}/fields returns one entry per field.

JSON
{
  "fields": [
    { "slug": "field_34", "name": "Customer Name", "type": "Text" },
    { "slug": "field_35", "name": "Status", "type": "Select" },
    { "slug": "field_36", "name": "Assigned Technician", "type": "Join" }
  ],
  "total_items": 3,
  "type": "success"
}
  • slug is the key you use for this field when you read, filter or save records.
  • type is the field type as the API stores it. Connection fields report Join.

Get full field details #

GET /api/v1/data-tables/{tableId}/full-fields-info adds the details you need to build a form or validate data before you save it. Every field has these properties:

PropertyWhat it holds
slug, name, typeAs in the basic list
fieldIdThe field's ID
descriptionThe field description, or an empty string
default_valueThe default value, when the field has one

Some field types add more:

Field typeExtra properties
Text, Number, Phone, Emailis_unique
Decision Boxdefault_value is 1 (checked) or 0
Date, Time, Date/Timedefault_value_type, and default_value when the default is a specific date or time
Connection (Join)join with join_type, data_table_id (the connected table), field_slug and field_id (the connected table's display field)
Checkbox, Radio, Select, Multi-Selectoptions as a list of label and value, and allow_diff_val (1 when the options save a value different from their label)
Address, Namefields: the parts of the field, each with key and name
JSON
{
  "slug": "field_35",
  "fieldId": "K2ejlOQo9B",
  "name": "Status",
  "type": "Select",
  "description": "",
  "default_value": "Open",
  "options": [
    { "label": "Open", "value": "Open" },
    { "label": "Closed", "value": "Closed" }
  ],
  "allow_diff_val": "0"
}

List the user roles #

GET /api/v1/roles returns every role in the app with its encoded id.

JSON
{
  "items": [
    {
      "id": "DVWQWRNZ49",
      "name": "Dispatcher",
      "description": "Schedules jobs",
      "enable_stripe": "No"
    }
  ],
  "total_items": 1,
  "total_pages": 1,
  "current_page": 1,
  "type": "success"
}

enable_stripe is Yes when the role is tied to a Stripe subscription.

Get the whole app schema in one call #

If you need every table and field at once, turn on Allow App Schema on the API key and call one of these:

EndpointReturns
GET /api/v1/schemaThe app schema. It may answer with a redirect to a cached copy; let your client follow redirects. Add ?fresh=1 to skip the cache.
GET /api/v1/full-schemaThe schema plus every page and layout
GET /api/v1/deep-schemaThe full schema plus rules, pipes, custom code and where each pipe and PDF is used (the same as full-schema?deep=1)

Without Allow App Schema these endpoints answer 412.

What to do with it #

Read the structure once and cache it: tables and fields change only when someone edits the app in the builder. You can use it to map field slugs to names, build forms or generate types in your own code. For a worked example that writes the tables and fields into a spreadsheet, see Save tables and fields into a spreadsheet.

Common problems #

ResponseCause
412 "The method being used is disabled for this API key."Allow Reads (or Allow App Schema for the schema endpoints) is off on the API key
412 with a plan messageYour plan does not include API access
type: error "Data Table not found"The table ID is wrong or belongs to another app

Was this page helpful?

Something wrong or missing on this page? Tell us.