> For the complete documentation index, see [llms.txt](https://docs.bloodgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloodgpt.com/patients-and-catalog/product-catalog.md).

# Product Catalog API

Manage your organization's product catalog for blood-test-driven recommendations

The Product Catalog API stores your organization's products (e.g. supplements). Products are matched against blood test results to power product recommendations. The catalog is scoped to your organization.

All endpoints require `Authorization: Bearer YOUR_API_KEY`.

***

## Bulk Import / Upsert

**Endpoint:** `POST /api/v1/product-catalog/import`

Imports between **1 and 5000** products in one request. Products are **upserted by `sku`** — an existing product with the same SKU is updated, otherwise a new one is created. Products **without a `name` are skipped** (not rejected).

### Request

```json
{
  "products": [
    {
      "name": "Vitamin D3 2000 IU",
      "sku": "VD3-2000",
      "description": "Cholecalciferol softgels",
      "url": "https://shop.example.com/vd3-2000",
      "price": 12.99,
      "currency": "USD",
      "categories": ["vitamins", "immune"]
    }
  ]
}
```

| Field         | Type             | Required    | Description                                                                     |
| ------------- | ---------------- | ----------- | ------------------------------------------------------------------------------- |
| `name`        | string           | Recommended | Product name. Items without it are skipped.                                     |
| `sku`         | string           | No          | Stable identifier used for upsert. Without it, a new product is always created. |
| `description` | string           | No          | Free-text description                                                           |
| `url`         | string           | No          | Link to the product page                                                        |
| `price`       | number \| string | No          | Numeric price (strings are coerced to numbers)                                  |
| `currency`    | string           | No          | ISO currency code. Defaults to `BYN`.                                           |
| `categories`  | string\[]        | No          | Category tags (used for filtering)                                              |

{% hint style="info" %}
The per-item shape is lenient: unknown and localized keys are accepted and stored — for example `composition`/`состав`, `usage`/`способ_применения`, `contraindications`/`противопоказания`, and `imageUrl`/`image`.
{% endhint %}

### Response (200 OK)

```json
{
  "status": "ok",
  "created": 12,
  "updated": 3,
  "total": 15
}
```

Returns `422 invalid_input` if `products` is missing, empty, or exceeds 5000 items.

***

## List Products

**Endpoint:** `GET /api/v1/product-catalog`

### Query Parameters

| Parameter  | Type    | Default | Description                                                                   |
| ---------- | ------- | ------- | ----------------------------------------------------------------------------- |
| `active`   | string  | —       | Active products only by default; pass `active=false` to include inactive ones |
| `category` | string  | —       | Filter to products tagged with this category                                  |
| `limit`    | integer | 100     | Max products to return (max 1000)                                             |
| `offset`   | integer | 0       | Number of products to skip                                                    |

### cURL Example

```bash
curl "https://sandbox.bloodgpt.com/api/v1/product-catalog?category=vitamins&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json
{
  "products": [
    {
      "id": "clprod123",
      "name": "Vitamin D3 2000 IU",
      "sku": "VD3-2000",
      "url": "https://shop.example.com/vd3-2000",
      "price": 12.99,
      "currency": "USD",
      "categories": ["vitamins", "immune"],
      "description": "Cholecalciferol softgels",
      "is_active": true
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

***

## Clear Catalog

**Endpoint:** `DELETE /api/v1/product-catalog`

Deletes **all** products in your organization's catalog. There is no per-product delete — re-import to replace the catalog.

```bash
curl -X DELETE https://sandbox.bloodgpt.com/api/v1/product-catalog \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json
{
  "status": "ok",
  "deleted": 42
}
```