# Tables

A **Table** is a spreadsheet-like resource: rows, columns, views, and aggregations. It is flatter than an [Object](/docs/concepts/objects) — it does not have record types, and it does not carry CRM-style activities like notes or tasks. It **can** still link to other resources (Objects or Tables) through a `relation` column, and it **can** hold files via a `file` column.

If you need a dataset that flows interact with (lookups, writes, conditionals) without the CRM-style overhead, use a Table. If you need a typed entity with multiple record types and full activity tracking, use an Object.

> All `tables` endpoints require a **USER** API key. See [Authentication](/docs/authentication).


## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | number |  |
| `name` | string | Internal identifier. Use as `:name` in route params. |
| `display_name` | string | User-facing name. |
| `type` | enum | Always `"table"` (vs `"object"` for [Objects](/docs/concepts/objects)). |
| `custom` | boolean | `true` for tables you created. |
| `description` | string? |  |
| `emoji` | string? | A **Unicode emoji character** (e.g. `📊`, not an icon-name string). |
| `icon_color` | string? | Color name or hex. |
| `field_count` | number? | Number of columns. |
| `created_at` | string | ISO timestamp. |
| `updated_at` | string | ISO timestamp. |


Detail responses include `fields` and `views`. They also include a `record_types` array for shape compatibility, but Tables always carry a single implicit record type — categorization is not exposed.

## Columns

Tables use the same column types as Objects (see [Objects → Fields](/docs/concepts/objects#fields-columns)). Allowed types in the Public API: `string`, `number`, `boolean`, `date`, `dateOnly`, `tags` / `select`, `relation` (limited), `file`, `avatar`. Internal types are rejected.

## Tables vs Objects

| Feature | Tables | Objects |
|  --- | --- | --- |
| Multiple record types | ❌ | ✅ |
| Relations to Objects / other Tables | ✅ | ✅ |
| Relations to Users | ❌ | ✅ |
| Notes attached to rows | ❌ | ✅ |
| Tasks attached to rows | ❌ | ✅ |
| `file` column type | ✅ | ✅ |
| Views | ✅ | ✅ |
| Aggregations | ✅ | ✅ |
| Exports (CSV / XLSX) | ✅ | ✅ |


When in doubt: pick **Object** if records need record types, notes/tasks, or links to Users; pick **Table** for flatter datasets used by flows and workflows.

## Sub-resources

Mounted under `/public/v1/tables/{name}/...`:

| Sub-resource | Purpose |
|  --- | --- |
| `field` | Manage columns. |
| `option` | Manage `tags`/`select` field options. |
| `record` / `row` | List, get, create, update, delete rows. |
| `view` | Saved view configurations. |
| `aggregation` | Per-view aggregations. |
| `export` | Export rows as XLSX or CSV. |


To attach files to a row, use a column of type `file` rather than a row-level activity.

## Operations (top-level)

| Verb | Path | Purpose |
|  --- | --- | --- |
| `GET` | `/public/v1/tables` | List |
| `POST` | `/public/v1/tables` | Create |
| `GET` | `/public/v1/tables/{name}` | Detail |
| `GET` | `/public/v1/tables/{name}/schema` | Schema-only |
| `PATCH` | `/public/v1/tables/{name}` | Update display name, emoji, color, description |
| `DELETE` | `/public/v1/tables/{name}` | Delete |


## CLI


```bash
frontline table list
frontline table get my_table
frontline table create my_table --data '{"displayName":"My Table","columns":[{"name":"Name","type":"string","metadata":{"format":"text"}}]}'
frontline table row create my_table --data '{"Name":"Acme"}'
frontline table export my_table --format csv
```