> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create table

> Create a table with its columns. Rate limit: 10 write requests per minute per workspace, one write at a time per workspace, plus 60 requests per minute per API key. 50 tables per UTC day per workspace.

Send a `name` and 1–50 `columns`. Each column has a `label` and an optional `type`: `text` (default), `email`, `phone`, `url`, `number` or `json`. Labels must be unique within the table, ignoring case, and table names must be unique within the workspace (`409` with `code: "table_name_conflict"`).

The response includes each column's `id`. Store these IDs: row values are keyed by column ID.

Each workspace can create 50 tables per UTC day through the API.

> [!NOTE]
>
> Paid plans only. No credits are charged. Limits: 10 write requests per minute per workspace, one write at a time per workspace, plus 60 requests per minute per API key. 50 tables per UTC day per workspace. See the [Tables API overview](https://docs.airscale.io/api-reference/tables/overview.md) for every limit.

## Authentication

Send `Authorization: Bearer $AIRSCALE_API_KEY`. The key determines the workspace. See [Authentication](https://docs.airscale.io/api-reference/authentication.md).

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `Idempotency-Key` | header | No | Reuse the same key and identical body when retrying this operation. A changed body with the same key returns 409 idempotency\_conflict. |

## JSON body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Table name, unique among the workspace's tables. 1–200 characters. |
| `columns` | array | Yes | Columns in display order. Labels must be unique, ignoring case. 1–50 items. |
| `columns[].label` | string | Yes | 1–200 characters. |
| `columns[].type` | string | No | One of: `text`, `email`, `phone`, `url`, `number`, `json` Default: `text`. |

## Request example

Replace path variables with IDs returned by the API. Column UUIDs in the example body must belong to your table.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST "https://api.airscale.io/v1/tables" \
  --header "Authorization: Bearer $AIRSCALE_API_KEY" \
  --header "Idempotency-Key: createTable-001" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Prospects",
  "columns": [
    {
      "label": "Name",
      "type": "text"
    },
    {
      "label": "Email",
      "type": "email"
    },
    {
      "label": "Employees",
      "type": "number"
    }
  ]
}'
```

## Response

### 201

The table was created.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "table": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Prospects",
    "createdAt": "2026-10-28T09:15:02.481Z",
    "updatedAt": "2026-10-28T09:15:02.481Z",
    "columns": [
      {
        "id": "0d9f2756-17db-42e5-b9d5-1e1c564a1079",
        "label": "Name",
        "type": "text",
        "fieldKey": "field_1"
      },
      {
        "id": "7711ed25-4a90-413d-96e0-67ed2341b1ca",
        "label": "Email",
        "type": "email",
        "fieldKey": "field_2"
      },
      {
        "id": "c3a1f7e2-5b8d-4e6f-9a2b-1d4c7e8f0a3b",
        "label": "Employees",
        "type": "number",
        "fieldKey": "field_3"
      }
    ]
  }
}
```

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid body, duplicate column labels or an unsupported column type. |
| 401 | Missing or invalid API key. |
| 403 | The workspace does not have an active paid plan. |
| 409 | A table with this name already exists. |
| 413 | Body larger than 8 MiB. |
| 429 | A rate limit, the one-write-at-a-time rule or a daily limit was reached. Wait for Retry-After before retrying. |
| 502 | The service could not be reached. Retry with backoff. |
| 503 | The service is at capacity or temporarily unavailable. Retry after Retry-After. |
| 504 | The request timed out after 30 seconds. A write may still have been applied; check the result before retrying it. |

See [limits, retries and error codes](https://docs.airscale.io/api-reference/tables/overview.md#limits) for shared behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.