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

Source: https://tadabase.com/docs/developers/tables-and-fields-api  
Status: Verified Nov 17, 2026. Checked against the current product

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](https://tadabase.com/docs/developers/getting-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."

| Endpoint | Returns |
| --- | --- |
| `GET /api/v1/data-tables` | Every visible table: `id` and `name` |
| `GET /api/v1/data-tables/{tableId}/fields` | The table's fields: `slug`, `name`, `type` |
| `GET /api/v1/data-tables/{tableId}/full-fields-info` | The table's fields with defaults, options and connection details |
| `GET /api/v1/roles` | The app's user roles |

## List the tables

```bash
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:

| Property | What it holds |
| --- | --- |
| `slug`, `name`, `type` | As in the basic list |
| `fieldId` | The field's ID |
| `description` | The field description, or an empty string |
| `default_value` | The default value, when the field has one |

Some field types add more:

| Field type | Extra properties |
| --- | --- |
| Text, Number, Phone, Email | `is_unique` |
| Decision Box | `default_value` is `1` (checked) or `0` |
| Date, Time, Date/Time | `default_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-Select | `options` as a list of `label` and `value`, and `allow_diff_val` (1 when the options save a value different from their label) |
| Address, Name | `fields`: 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:

| Endpoint | Returns |
| --- | --- |
| `GET /api/v1/schema` | The 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-schema` | The schema plus every page and layout |
| `GET /api/v1/deep-schema` | The 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](https://tadabase.com/docs/developers/save-tables-and-fields-into-spreadsheet).

## Common problems

| Response | Cause |
| --- | --- |
| `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 message | Your plan does not include API access |
| `type: error` "Data Table not found" | The table ID is wrong or belongs to another app |
