# Workflow: Import CSV Data into a Store

Use this workflow when a user has tabular data that should become a NiftyImages Store.

## Before live calls

- If no NiftyImages API key is available, ask the user for one before calling `/v2`.
- Do not invent, guess, log, or expose the API key.
- If the user only wants planning or code generation, continue without an API key.
- A regular account API key can create stores. A Store API Key starts with `store-` and can only import records into its assigned store.
- If key scope is unknown, call `GET /v2/stores/access` first. When it returns `scope: "store"`, use the returned `storeId` and do not call `POST /v2/stores`.

## Recommended agent flow

1. Read CSV headers and sample rows.
2. Infer a store schema.
3. Choose at least one unique property when possible.
4. With an account API key, create the store with `POST /v2/stores`; with a Store API Key, use the assigned existing store from `GET /v2/stores/access`.
5. Validate sample records with `POST /v2/stores/{storeId}/records/validate`.
6. Upsert rows in batches of up to 100 with `POST /v2/stores/{storeId}/records/batch`.
7. Confirm imported count with `POST /v2/stores/{storeId}/records/count`.

## Create store

Requires an account API key. Skip this step when using a Store API Key.

```bash
curl https://dev.niftyimages.com/v2/stores \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Demo Guests",
    "properties": [
      { "name": "email", "type": "string", "required": true, "unique": true },
      { "name": "firstName", "type": "string", "required": false },
      { "name": "state", "type": "string", "required": false },
      { "name": "status", "type": "string", "required": false }
    ]
  }'
```

## Validate one row

```bash
curl https://dev.niftyimages.com/v2/stores/{storeId}/records/validate \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "firstName": "Avery",
    "state": "CA",
    "status": "VIP"
  }'
```

## Batch upsert rows

```bash
curl https://dev.niftyimages.com/v2/stores/{storeId}/records/batch \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "email": "developer@example.com",
        "firstName": "Avery",
        "state": "CA",
        "status": "VIP"
      }
    ]
  }'
```

## Agent notes

- Batch size limit is 100 records.
- If no field is unique, records receive random ids and CSV re-imports may create duplicates.
- Prefer strings for ambiguous CSV columns unless values clearly map to number, boolean, or datetime.
- Report per-record failures after each batch.