---
title: "Add a table"
description: "Adds a table."
canonical: "https://gtable.app/docs/builder-api/tables/create"
updated: "2026-10-05"
---

# Add a table

`POST https://studio.gtable.app/v1/apps/{appId}/tables`

Adds a table.

Ids are the platform's to mint and are opaque: leave `id` and every field's `id` out and you get `tbl_…` and `fld_…` back in the response. Send them only when you are recreating something whose ids you already hold. Goes through the same validation the Studio UI uses, so the two cannot drift.

Requires the `schema:write` scope. Operation `tables.create`. MCP tool `tables_create`. CLI, once published: `gtable tables create`.

## Path parameters

| Name    | Type   | Required | Description |
| ------- | ------ | -------- | ----------- |
| `appId` | string | yes      |             |

## Headers

| Name              | Type   | Required | Description                                                                                                                                                                                                                                                        |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | string | no       | Any unique string. Sending the same key with the same request again returns the first response (marked `Idempotency-Replayed: true`) instead of running it twice. Reusing it for a different request is refused with 409. Kept for 24 hours. Up to 255 characters. |

## Request body

| Field            | Type          | Required | Description            |
| ---------------- | ------------- | -------- | ---------------------- |
| `name`           | string        | yes      | Up to 120 characters.  |
| `plural`         | string        | no       | Up to 120 characters.  |
| `description`    | string        | no       | Up to 2000 characters. |
| `id`             | string        | no       |                        |
| `primaryField`   | string        | no       | Up to 120 characters.  |
| `primaryFieldId` | string        | no       |                        |
| `fields`         | FieldInput\[] | yes      | 1 to 200 items.        |