Quickstart

In your app, open Settings, then Connections, then For developers, and create a key. Pick the scopes it needs (records:read and records:write for this guide). Copy it now: it is shown once.

An app lives under its suite’s address, at its own path:

export GTABLE_TOKEN="gt_live_…"
export GTABLE_APP="https://your-suite.gtable.app/your-app"

curl "$GTABLE_APP/v1/schema" -H "Authorization: Bearer $GTABLE_TOKEN"

The answer lists your tables and, in each, the fields you can read. Table ids look like tbl_8fj3kq2wmv5d and field ids like fld_3ns8wq5ke2pb. Ids never change; names can.

curl "$GTABLE_APP/v1/tables/tbl_8fj3kq2wmv5d/records?limit=5" \
  -H "Authorization: Bearer $GTABLE_TOKEN"

Every response has the same envelope. A record is keyed by field id, and meta.fields says which name each id has today, so you can show names without a second call:

{
  "data": [{ "id": "rec_4nqw8e2hzk7s", "fld_3ns8wq5ke2pb": "First record", "fld_7qk2mv9xp4ht": 20500 }],
  "meta": {
    "nextCursor": "eyJ…",
    "hasMore": true,
    "fields": { "fld_3ns8wq5ke2pb": "Name", "fld_7qk2mv9xp4ht": "Amount" }
  }
}

Send an Idempotency-Key with every write. If the request is retried, and in a CI job it will be, you get the first answer back instead of a second row.

curl -X POST "$GTABLE_APP/v1/tables/tbl_8fj3kq2wmv5d/records" \
  -H "Authorization: Bearer $GTABLE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"Name":"Second record","Amount":1000}]}'

When you write, a field’s exact name works in place of its id. A key that is neither is refused with a 422 naming it, so a typo never becomes an empty row.

In the same Connections screen, choose Copy setup prompt and paste it into Claude, ChatGPT, Cursor or VS Code. The agent adds the server and you sign in in your browser. See Set up your agent.