---
title: "Developer quickstart"
description: "Create an API key or sign in with the CLI, inspect your readable schema, list records, and write a record with an idempotency key."
canonical: "https://grid82.com/docs/start/dev-quickstart"
updated: "2026-11-20"
---

# Developer quickstart

You can interact with any Grid82 app over REST or with the `grid82` CLI. Every request runs as you and obeys your exact role permissions.

1. **Get a credential**

   **CLI (OAuth in browser)**

   Install or run `@grid82/cli` (Node.js 22.12 or later) and sign in to your suite:

   ```bash
   npm install --global @grid82/cli
   grid82 auth login --target https://your-suite.grid82.app --plane app
   ```

   If you are on a headless machine without a browser, add `--device` to use the OAuth device code flow.

   **API key (for scripts and CI)**

   In your Runtime app, open the app menu, click **Settings**, go to **Connections**, and select **For developers**. Create a key with `records:read` and `records:write`, copy it (keys start with `g82_` and are shown once), and export it:

   ```bash
   export GRID82_TOKEN="g82_live_..."
   export GRID82_APP="https://your-suite.grid82.app/your-app"
   ```
2. **Inspect the tables and fields you can read**

   ```bash title="curl"
   curl "$GRID82_APP/v1/schema" \
     -H "Authorization: Bearer $GRID82_TOKEN"
   ```

   ```bash title="CLI"
   grid82 schema get --app "$GRID82_APP"
   ```

   The response returns every table you may read, with permanent IDs (`tbl_...` and `fld_...`), field types, and select options. Always key automated code on IDs rather than display names, because display names can change.
3. **List records**

   ```bash title="curl"
   curl "$GRID82_APP/v1/tables/tbl_8fj3kq2wmv5d/records?limit=5" \
     -H "Authorization: Bearer $GRID82_TOKEN"
   ```

   ```bash title="CLI"
   grid82 records list tbl_8fj3kq2wmv5d --limit 5 --app "$GRID82_APP"
   ```

   Records use field IDs as keys, and `meta.fields` includes the current ID-to-name map for rendering labels without a second request:

   ```json
   {
     "data": [
       {
         "id": "rec_4nqw8e2hzk7s",
         "fld_3ns8wq5ke2pb": "Northwind Enterprise Renewal",
         "fld_7qk2mv9xp4ht": 48000
       }
     ],
     "meta": {
       "nextCursor": "eyJ...",
       "hasMore": true,
       "fields": {
         "fld_3ns8wq5ke2pb": "Name",
         "fld_7qk2mv9xp4ht": "Amount"
       }
     }
   }
   ```
4. **Create a record safely with an idempotency key**

   Pass an `Idempotency-Key` header on `POST` writes so retried requests replay the original result instead of duplicating records. When writing records, you can pass either field IDs or exact field names:

   ```bash title="curl"
   curl -X POST "$GRID82_APP/v1/tables/tbl_8fj3kq2wmv5d/records" \
     -H "Authorization: Bearer $GRID82_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"records":[{"Name":"Meridian Annual Support","Amount":24000}]}'
   ```

   ```bash title="CLI"
   grid82 records create tbl_8fj3kq2wmv5d \
     --records '[{"Name":"Meridian Annual Support","Amount":24000}]' \
     --app "$GRID82_APP"
   ```
5. **Fetch your personal OpenAPI spec**

   An app's OpenAPI spec is generated per caller and excludes hidden tables and fields:

   ```bash
   curl "$GRID82_APP/v1/openapi.json" \
     -H "Authorization: Bearer $GRID82_TOKEN" > app-openapi.json
   ```

## Next steps

- Read [REST conventions](/docs/developers/rest/conventions) for envelopes, cursor pagination, and optimistic concurrency.
- Read [CLI overview](/docs/developers/cli/overview) for environment variables, exit codes, and `grid82 mcp`.
- Connect an AI assistant with [Set up your agent](/docs/developers/agents/setup).
