---
title: "Quickstart"
description: "Make a key in an app you were invited into, read a table and write a record with curl, then hand the same access to an agent."
canonical: "https://gtable.app/docs/start/quickstart"
updated: "2026-10-05"
---

# Quickstart

This takes five minutes and needs an app you can sign in to. Everything below acts as you: the
key sees exactly what you see in the app, and nothing more.

1. **Make a key**

   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:

   ```bash
   export GTABLE_TOKEN="gt_live_…"
   export GTABLE_APP="https://your-suite.gtable.app/your-app"
   ```
2. **See what you can reach**

   ```bash
   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.
3. **Read some records**

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

   ```json
   {
     "data": [{ "id": "rec_4nqw8e2hzk7s", "fld_3ns8wq5ke2pb": "First record", "fld_7qk2mv9xp4ht": 20500 }],
     "meta": {
       "nextCursor": "eyJ…",
       "hasMore": true,
       "fields": { "fld_3ns8wq5ke2pb": "Name", "fld_7qk2mv9xp4ht": "Amount" }
     }
   }
   ```
4. **Write one**

   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.

   ```bash
   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.
5. **Hand it to an agent**

   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](/docs/agents/setup).

## Where next

- [Conventions](/docs/api/conventions): the envelope, pagination, filters and how records look
  on the wire.
- [Retries and idempotency](/docs/api/idempotency): making a script safe to run twice.
- [The App API reference](/docs/app-api/records/list): every operation of an app.
- Your own OpenAPI document, which describes your tables:
  `curl "$GTABLE_APP/v1/openapi.json" -H "Authorization: Bearer $GTABLE_TOKEN"`.