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

# API quickstart

> From zero to your first product upserted via the API in under five minutes.

This walks you through the full inbound and outbound flow: verify your key, create one product, bulk-upsert many, read enriched data back, and check a job status. By the end you will have working `curl` commands and a clear path to scale up to full catalog sync.

## 1. Get an API key

Follow the steps in [Authentication](/api-reference/authentication) to generate a key from **Settings → Integrations**. Export it for the rest of this page:

```bash theme={null}
export RETAILGRID_API_KEY="rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## 2. Verify the key works

```bash theme={null}
curl https://clientapi.retailgrid.io/v1/auth/verify \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

A `200` with `"ok": true` means you are good to go.

## 3. Create one product

Pick a product id you control - it is the stable identifier you will use to update or delete this product later. UUIDs are fine, but any string works.

```bash theme={null}
PRODUCT_ID="11111111-2222-3333-4444-555555555555"

curl -X POST "https://clientapi.retailgrid.io/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "SKU-DEMO-001",
    "product_name": "Demo running shoe",
    "brand": "Acme",
    "manufacturer": "Acme Footwear",
    "product_type": "shoe",
    "status": "active"
  }'
```

A `201 Created` response returns the full product record, including the internal `id` Retailgrid assigned.

## 4. Bulk-upsert many products at once

For more than a handful of records, prefer `/bulk`. It accepts up to a few thousand items in one request and returns per-item results.

```bash theme={null}
curl -X POST "https://clientapi.retailgrid.io/v1/products/bulk" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": "SKU-DEMO-002", "product_name": "Demo trail shoe", "brand": "Acme"},
      {"product_id": "SKU-DEMO-003", "product_name": "Demo road shoe",  "brand": "Acme"}
    ]
  }'
```

The response has one `BulkItemResult` per input row, so partial failures do not block the whole batch. See [Conventions](/api-reference/conventions) for details.

## 5. Read what you've loaded

The API reads as well as writes. Pull enriched products (canonical fields plus any custom columns added at import) for ERP or BI ingestion:

```bash theme={null}
curl -s "https://clientapi.retailgrid.io/v1/products?updated_after=2026-05-01T00:00:00Z&limit=500" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

The same pattern works for transactions:

```bash theme={null}
curl -s "https://clientapi.retailgrid.io/v1/transactions?updated_after=2026-05-01T00:00:00Z&limit=1000" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

To export the full row contents of a grid - including custom and formula / calculated columns - list your grids first, then pull the rows:

```bash theme={null}
# List grids
curl -s "https://clientapi.retailgrid.io/v1/grids" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

# Pull rows from a grid
curl -s "https://clientapi.retailgrid.io/v1/grids/grd_01HX2K8E4Y/rows?limit=5000" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

All read endpoints support cursor pagination and an `updated_after` filter for delta pulls. See [Get grid rows](/api-reference/grids/get-rows) for the full column-selection options.

## 6. Async CSV uploads

For full-catalog refreshes, use the CSV import endpoints. They return immediately with a `job_id`:

```bash theme={null}
curl -X POST "https://clientapi.retailgrid.io/v1/imports/products" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -F "file=@products.csv"
```

```json theme={null}
{ "job_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" }
```

Then poll for status:

```bash theme={null}
curl "https://clientapi.retailgrid.io/v1/jobs/0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

When `"status": "completed"`, the data is live in your Retailgrid grids.

## What's next

* [Imports vs bulk](/api-reference/imports-vs-bulk) - decide which endpoint family fits your pipeline.
* [Conventions](/api-reference/conventions) - the patterns every endpoint follows.
* [Errors](/api-reference/errors) - what 422 responses look like and how to fix them.
* [List products](/api-reference/products/list) and [Get grid rows](/api-reference/grids/get-rows) - the read-side reference.