> ## 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.

# Introduction

> The Retailgrid Public API lets you push and pull product, variant, transaction, and competitor data, plus export full grid contents - programmatically.

The Retailgrid Public API is the programmatic counterpart to the in-app upload and export flows. Use it when you want to keep Retailgrid in sync with your source systems on a schedule, or feed enriched data back into your ERP and BI tools, instead of uploading and downloading CSVs by hand.

## Base URL

```
https://clientapi.retailgrid.io
```

All endpoints live under `/v1`. Future breaking changes will land under a new prefix; minor additions will not change `/v1`.

## What you can do today

* **Push catalog data** - create, patch, delete, and bulk-upsert products and product variants.
* **Push transactions** - create, patch, delete, and bulk-upsert sales transactions.
* **Push competitor prices** - create, patch, delete, and bulk-upsert observed competitor prices.
* **Pull catalog and transactions** - list enriched products and sales transactions for ERP / BI ingestion. Includes custom columns added at import time.
* **Export grids** - list grids in your account and pull the full row contents of any grid, including canonical, custom, and formula / calculated columns.
* **Upload CSVs asynchronously** - submit a multipart CSV to `/v1/imports/*` and poll a job handle.
* **Verify your API key** - sanity-check that your key works before hooking up a pipeline.

<Note>
  Retailgrid keys the catalog at the SKU level. `item_id` is the required unique identifier for each item, and the key used to link transactions, store-level data, and competitor prices back to your catalog. `product_id` is an optional product-level code that groups related items / variants under one product.
</Note>

## When to use the API vs other paths

<CardGroup cols={2}>
  <Card title="Public API" icon="plug" href="/api-reference/quickstart">
    For continuous, machine-to-machine sync from your ERP, PIM, or warehouse - in or out.
  </Card>

  <Card title="CSV upload in the app" icon="file-csv" href="/get-started/quickstart">
    For one-off loads or when an analyst is driving. Same data, manual flow.
  </Card>
</CardGroup>

## Conventions

A few things are worth reading once before you start integrating:

* [Authentication](/api-reference/authentication) - how Bearer keys work and where to issue one.
* [Conventions](/api-reference/conventions) - bulk endpoints, async jobs, decimals as strings, timestamps in UTC.
* [Imports vs bulk](/api-reference/imports-vs-bulk) - which endpoint family to pick for which job.
* [Errors](/api-reference/errors) - status codes and the validation-error shape.

## Versioning

The current version is `v1`. Additive changes (new fields, new endpoints, new optional parameters) ship without notice. Breaking changes will be announced in the [API changelog](/api-reference/changelog) and shipped under a new version prefix.