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

# Catalog API

> API reference for products, categories, attributes, and taxonomies

# Catalog API

The Catalog API provides endpoints for managing products, categories, attributes, and taxonomies.

<Note>
  **Scope**: Tenant-scoped; requires authenticated org context\
  **Availability**: Not available in SuperAdmin
</Note>

## Authentication

All requests require authentication. Include your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/api-reference/authentication) for details.

## Base URL

```
https://app.betterdata.co/api
```

## Headers

All requests must include:

```
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

{/* this block is generated; do not edit by hand */}

| Method   | Path                                      | Summary                            | Auth    | Stability | Permissions                       |
| -------- | ----------------------------------------- | ---------------------------------- | ------- | --------- | --------------------------------- |
| `GET`    | `/api/products`                           | List products                      | session | stable    | products.read                     |
| `POST`   | `/api/products`                           | Create a product                   | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]`                      | Get a specific product             | session | stable    | products.read                     |
| `PATCH`  | `/api/products/[id]`                      | Update a product                   | session | stable    | products.write                    |
| `DELETE` | `/api/products/[id]`                      | Delete a product                   | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]/attributes`           | Get product attributes             | session | stable    | products.read                     |
| `POST`   | `/api/products/[id]/attributes`           | Create product attributes          | session | stable    | products.write                    |
| `POST`   | `/api/products/[id]/attributes/apply`     | Apply product attributes           | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]/categories`           | Get product categories             | session | stable    | products.read                     |
| `POST`   | `/api/products/[id]/categories`           | Assign product categories          | session | stable    | products.write                    |
| `POST`   | `/api/products/[id]/categories/apply`     | Apply product categories           | session | stable    | products.write                    |
| `POST`   | `/api/products/[id]/categories/suggest`   | Suggest product categories         | session | beta ⚠️   | products.read                     |
| `GET`    | `/api/products/[id]/history`              | Get product history                | session | stable    | products.read                     |
| `GET`    | `/api/products/[id]/inventory-levels`     | Get product inventory levels       | session | stable    | products.read, inventory.read     |
| `GET`    | `/api/products/[id]/links`                | Get product links                  | session | stable    | products.read                     |
| `POST`   | `/api/products/[id]/links`                | Create product link                | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]/variants`             | List product variants              | session | stable    | products.read                     |
| `POST`   | `/api/products/[id]/variants`             | Create product variant             | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]/variants/[variantId]` | Get product variant                | session | stable    | products.read                     |
| `PATCH`  | `/api/products/[id]/variants/[variantId]` | Update product variant             | session | stable    | products.write                    |
| `DELETE` | `/api/products/[id]/variants/[variantId]` | Delete product variant             | session | stable    | products.write                    |
| `GET`    | `/api/products/[id]/versions`             | Get product versions               | session | stable    | products.read                     |
| `GET`    | `/api/stock-requests/products/search`     | Search products for stock requests | session | stable    | stockrequests.read, products.read |
| `GET`    | `/api/taxonomies`                         | List taxonomies                    | session | stable    | taxonomies.read                   |
| `GET`    | `/api/taxonomies/[id]/nodes/search`       | Search taxonomy nodes              | session | stable    | taxonomies.read                   |
| `GET`    | `/api/taxonomies/[id]/tree`               | Get taxonomy tree                  | session | stable    | taxonomies.read                   |

## Example Requests

### List Products

```bash theme={null}
curl -X GET "https://app.betterdata.co/api/products?categoryId=cat_123&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "products": [
    {
      "id": "prod_123",
      "productName": "Product Name",
      "globalSku": "SKU-123",
      "description": "Product description",
      "categoryId": "cat_123",
      "categoryName": "Category Name",
      "status": "ACTIVE",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 150,
    "totalPages": 3
  }
}
```

### Create Product

```bash theme={null}
curl -X POST "https://app.betterdata.co/api/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "New Product",
    "globalSku": "SKU-456",
    "description": "Product description",
    "categoryId": "cat_123",
    "identifiers": [
      {
        "type": "UPC",
        "value": "123456789012"
      }
    ],
    "attributes": {
      "color": "Blue",
      "size": "Large"
    }
  }'
```

**Response:**

```json theme={null}
{
  "product": {
    "id": "prod_456",
    "productName": "New Product",
    "globalSku": "SKU-456",
    "description": "Product description",
    "categoryId": "cat_123",
    "status": "ACTIVE",
    "createdAt": "2024-03-01T00:00:00Z"
  }
}
```

### Get Taxonomy Tree

```bash theme={null}
curl -X GET "https://app.betterdata.co/api/taxonomies/tax_123/tree" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "taxonomy": {
    "id": "tax_123",
    "name": "Product Taxonomy",
    "rootNodes": [
      {
        "id": "node_1",
        "name": "Category 1",
        "code": "CAT1",
        "children": [
          {
            "id": "node_2",
            "name": "Subcategory 1.1",
            "code": "CAT1.1",
            "children": []
          }
        ]
      }
    ]
  }
}
```

## Common Errors

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

**Cause**: Missing or invalid API key.

**Solution**: Include a valid API key in the `Authorization` header.

### 400 Bad Request

```json theme={null}
{
  "error": "Validation error",
  "details": {
    "productName": ["Required"],
    "globalSku": ["Must be unique"]
  }
}
```

**Cause**: Invalid request parameters or validation errors.

**Solution**: Review the request body and ensure all required fields are provided with valid values.

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden"
}
```

**Cause**: Insufficient permissions. Product creation requires `products.write` permission.

**Solution**: Ensure your API key has the required permissions.

### 404 Not Found

```json theme={null}
{
  "error": "Product not found"
}
```

**Cause**: The requested product doesn't exist or isn't accessible.

**Solution**: Verify the product ID and ensure you have access to it.

### 409 Conflict

```json theme={null}
{
  "error": "Product with SKU already exists"
}
```

**Cause**: Product with the same SKU already exists.

**Solution**: Use a unique SKU or update the existing product.

## Query Parameters

### List Products

* `categoryId`: Filter by category
* `search`: Search by product name or SKU
* `status`: Filter by status (`ACTIVE`, `PENDING`, `REVOKED`)
* `page`: Page number (default: 1)
* `limit`: Page size (default: 20, max: 100)
* `sortBy`: Sort field (default: `createdAt`)
* `sortOrder`: Sort order (`asc`, `desc`)

### List Categories

* `parentId`: Filter by parent category
* `search`: Search by category name
* `page`: Page number (default: 1)
* `limit`: Page size (default: 20, max: 100)

### Search Taxonomy Nodes

* `query`: Search query
* `parentId`: Filter by parent node
* `limit`: Result limit (default: 20, max: 100)

## Request/Response Schemas

### Product

```typescript theme={null}
{
  id: string;
  productName: string;
  globalSku: string;
  description?: string;
  categoryId?: string;
  categoryName?: string;
  status: "ACTIVE" | "PENDING" | "REVOKED";
  identifiers?: Array<{
    type: string;
    value: string;
  }>;
  attributes?: Record<string, unknown>;
  createdAt: string; // ISO datetime
  updatedAt: string; // ISO datetime
}
```

### Create Product Request

```typescript theme={null}
{
  productName: string;
  globalSku: string;
  description?: string;
  categoryId?: string;
  identifiers?: Array<{
    type: string;
    value: string;
  }>;
  attributes?: Record<string, unknown>;
}
```

### Category

```typescript theme={null}
{
  id: string;
  name: string;
  code?: string;
  description?: string;
  parentId?: string;
  createdAt: string; // ISO datetime
}
```

### Taxonomy Node

```typescript theme={null}
{
  id: string;
  name: string;
  code?: string;
  parentId?: string;
  children?: TaxonomyNode[];
}
```

***

## Related Pages

* [API Overview](/api-reference/overview)
* [Authentication](/api-reference/authentication)
* [Common Errors](/api-reference/errors)

***

## Permissions & Roles

<Tip>
  Catalog API access requires appropriate permissions:

  * **Read**: `products.read`, `categories.read`, `attributes.read`
  * **Write**: `products.write`, `categories.write`, `attributes.write`
</Tip>