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

# Products API: Catalog and PIM Management

> Manage your product catalog with the Synq PIM API. Create, update, and delete products, variants, brands, categories, attributes, and media assets.

The Products API gives you full control over your Product Information Management (PIM) catalog. Use it to build out your product hierarchy — from top-level products and their variants to the brands, categories, attributes, and media assets that describe them. Every request is scoped to your tenant and organization, so data is always isolated to your account.

<Note>
  All requests require three headers: `Authorization: Bearer YOUR_TOKEN`, `X-Tenant-ID: YOUR_TENANT_ID`, and `X-Org-ID: YOUR_ORG_ID`.
</Note>

***

## List products

Retrieve all products for your tenant. The response returns up to 100 products ordered by creation date.

**`GET /api/v1/pim/products`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Response

<ResponseField name="[]product" type="array">
  Array of product objects.

  <Expandable title="Product fields">
    <ResponseField name="id" type="string">UUID of the product.</ResponseField>
    <ResponseField name="org_id" type="string">Organization the product belongs to.</ResponseField>
    <ResponseField name="tenant_id" type="string">Tenant the product belongs to.</ResponseField>
    <ResponseField name="title" type="string">Product display name.</ResponseField>
    <ResponseField name="description" type="string">Product description.</ResponseField>
    <ResponseField name="category" type="string">Category slug or name.</ResponseField>
    <ResponseField name="status" type="string">Product status, e.g. `ACTIVE` or `DRAFT`.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/pim/products \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
      "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Classic Wool Sweater",
      "description": "100% merino wool, machine washable.",
      "category": "apparel",
      "status": "ACTIVE",
      "created_at": "2024-06-01T10:00:00Z",
      "updated_at": "2024-06-15T08:30:00Z"
    }
  ]
  ```
</CodeGroup>

***

## Create a product

Create a new product in your catalog. The new product is assigned `ACTIVE` status by default.

**`POST /api/v1/pim/products`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Body

<ParamField body="title" type="string" required>
  Display name of the product.
</ParamField>

<ParamField body="description" type="string">
  Long-form product description.
</ParamField>

<ParamField body="category" type="string">
  Category slug to associate with the product.
</ParamField>

### Response

Returns the newly created product object.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/products \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Classic Wool Sweater",
      "description": "100% merino wool, machine washable.",
      "category": "apparel"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Classic Wool Sweater",
    "description": "100% merino wool, machine washable.",
    "category": "apparel",
    "status": "ACTIVE",
    "created_at": "2024-06-01T10:00:00Z",
    "updated_at": "2024-06-01T10:00:00Z"
  }
  ```
</CodeGroup>

***

## Get a product

Retrieve a single product by its ID.

**`GET /api/v1/pim/products/{id}`**

### Path parameters

<ParamField path="id" type="string" required>
  UUID of the product to retrieve.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Classic Wool Sweater",
    "description": "100% merino wool, machine washable.",
    "category": "apparel",
    "status": "ACTIVE",
    "created_at": "2024-06-01T10:00:00Z",
    "updated_at": "2024-06-15T08:30:00Z"
  }
  ```
</CodeGroup>

***

## Update a product

Update the title, description, or category of an existing product.

**`PUT /api/v1/pim/products/{id}`**

### Path parameters

<ParamField path="id" type="string" required>
  UUID of the product to update.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

### Body

<ParamField body="title" type="string">
  New display name.
</ParamField>

<ParamField body="description" type="string">
  Updated product description.
</ParamField>

<ParamField body="category" type="string">
  Updated category slug.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{"title": "Premium Wool Sweater"}'
  ```
</CodeGroup>

***

## Delete a product

Permanently delete a product from your catalog. Returns `204 No Content` on success.

**`DELETE /api/v1/pim/products/{id}`**

### Path parameters

<ParamField path="id" type="string" required>
  UUID of the product to delete.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```
</CodeGroup>

***

## Create a variant

Add a variant (e.g. size, color combination) to an existing product.

**`POST /api/v1/pim/products/{product_id}/variants`**

### Path parameters

<ParamField path="product_id" type="string" required>
  UUID of the parent product.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

### Body

<ParamField body="sku" type="string">
  Stock-keeping unit identifier for this variant.
</ParamField>

<ParamField body="barcode" type="string">
  Barcode (e.g. UPC or EAN) for this variant.
</ParamField>

<ParamField body="price" type="number">
  Unit price of the variant.
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code, e.g. `USD`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/products/b2c3d4e5-f6a7-8901-bcde-f12345678901/variants \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "sku": "WOOL-SWTR-M-BLU",
      "price": 89.99,
      "currency": "USD"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "product_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "sku": "WOOL-SWTR-M-BLU",
    "price": "89.99",
    "currency": "USD",
    "created_at": "2024-06-01T10:05:00Z"
  }
  ```
</CodeGroup>

***

## Get dashboard stats

Return aggregate counts for your PIM catalog — total products, variants, brands, categories, and more.

**`GET /api/v1/pim/stats`**

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/pim/stats \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "total_products": 142,
    "active_products": 138,
    "total_variants": 610,
    "total_brands": 12,
    "total_categories": 8,
    "validation_issues": 3
  }
  ```
</CodeGroup>

***

## Export products

Queue an asynchronous export of your full product catalog. Returns `202 Accepted` immediately. You will be notified when the export file is ready for download.

**`POST /api/v1/pim/export`**

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/export \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "message": "Export job queued. You will be notified when the file is ready in Cloud Storage."
  }
  ```
</CodeGroup>

***

## Bulk jobs

Run or monitor large-scale catalog operations such as bulk price updates or mass status changes.

**`GET /api/v1/pim/bulk-jobs`** — list bulk jobs

**`POST /api/v1/pim/bulk-jobs`** — create a bulk job

### Query parameters (GET)

<ParamField query="type" type="string">
  Filter by job type. Defaults to `BULK_UPDATE`.
</ParamField>

### Body (POST)

<ParamField body="job_type" type="string" required>
  Type of bulk operation, e.g. `BULK_UPDATE` or `BULK_DELETE`.
</ParamField>

<ParamField body="payload" type="object">
  JSON payload passed to the job processor.
</ParamField>

<CodeGroup>
  ```bash cURL — Create bulk job theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/bulk-jobs \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "job_type": "BULK_UPDATE",
      "payload": { "status": "ACTIVE" }
    }'
  ```

  ```json Response theme={null}
  {
    "id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "job_type": "BULK_UPDATE",
    "status": "PENDING",
    "created_at": "2024-06-01T11:00:00Z"
  }
  ```
</CodeGroup>

***

## Validation issues

Retrieve a list of catalog validation problems, such as products missing required attributes or invalid SKUs.

**`GET /api/v1/pim/validation`**

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/pim/validation \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```
</CodeGroup>

***

## PIM audit events

Retrieve all PIM-specific audit events for your tenant, such as product creation, updates, and deletions.

**`GET /api/v1/pim/audit`**

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/pim/audit \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
      "action": "PRODUCT_CREATED",
      "entity_type": "PRODUCT",
      "entity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "actor_email": "alice@example.com",
      "ip_address": "203.0.113.42",
      "details": { "title": "Classic Wool Sweater" },
      "created_at": "2024-06-01T10:00:00Z"
    }
  ]
  ```
</CodeGroup>

***

## Categories

Organize products into a hierarchy of categories.

**`GET /api/v1/pim/categories`** — list categories

**`POST /api/v1/pim/categories`** — create a category

### Body (POST)

<ParamField body="name" type="string" required>
  Display name of the category.
</ParamField>

<ParamField body="slug" type="string" required>
  URL-safe identifier, e.g. `mens-outerwear`.
</ParamField>

<ParamField body="description" type="string">
  Optional description.
</ParamField>

<ParamField body="parentId" type="string">
  UUID of a parent category for nested hierarchies.
</ParamField>

<CodeGroup>
  ```bash cURL — Create category theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/categories \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Outerwear",
      "slug": "outerwear",
      "description": "Jackets, coats, and sweaters."
    }'
  ```
</CodeGroup>

***

## Brands

Associate products with brand identities.

**`GET /api/v1/pim/brands`** — list brands

**`POST /api/v1/pim/brands`** — create a brand

### Body (POST)

<ParamField body="name" type="string" required>
  Brand display name.
</ParamField>

<ParamField body="description" type="string">
  Brand description.
</ParamField>

<ParamField body="logoUrl" type="string">
  URL to the brand logo image.
</ParamField>

<CodeGroup>
  ```bash cURL — Create brand theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/brands \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Nordvik",
      "description": "Scandinavian outdoor apparel.",
      "logoUrl": "https://cdn.example.com/nordvik-logo.png"
    }'
  ```
</CodeGroup>

***

## Attributes, attribute groups, and templates

Define reusable product attributes and organize them into groups or product type templates.

| Method | Endpoint                       | Description             |
| ------ | ------------------------------ | ----------------------- |
| `GET`  | `/api/v1/pim/attributes`       | List attributes         |
| `POST` | `/api/v1/pim/attributes`       | Create attribute        |
| `GET`  | `/api/v1/pim/attribute-groups` | List attribute groups   |
| `POST` | `/api/v1/pim/attribute-groups` | Create attribute group  |
| `GET`  | `/api/v1/pim/templates`        | List product templates  |
| `POST` | `/api/v1/pim/templates`        | Create product template |

### Body for `POST /api/v1/pim/attributes`

<ParamField body="name" type="string" required>
  Attribute display name, e.g. `Color`.
</ParamField>

<ParamField body="slug" type="string" required>
  URL-safe key, e.g. `color`.
</ParamField>

<ParamField body="type" type="string">
  Data type: `TEXT`, `NUMBER`, `BOOLEAN`, or `SELECT`. Defaults to `TEXT`.
</ParamField>

<CodeGroup>
  ```bash cURL — Create attribute theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/attributes \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{"name": "Color", "slug": "color", "type": "TEXT"}'
  ```
</CodeGroup>

***

## Media

Attach images and other media assets to products or their variants.

**`GET /api/v1/pim/media`** — list media (supports `?product_id=` and `?variant_id=` query filters)

**`POST /api/v1/pim/media`** — attach a media asset

### Body (POST)

<ParamField body="url" type="string" required>
  Publicly accessible URL of the media asset.
</ParamField>

<ParamField body="product_id" type="string">
  UUID of the product to attach media to.
</ParamField>

<ParamField body="variant_id" type="string">
  UUID of the variant to attach media to.
</ParamField>

<ParamField body="alt_text" type="string">
  Accessible description of the image.
</ParamField>

<ParamField body="sort_order" type="integer">
  Display order (lower numbers appear first).
</ParamField>

<CodeGroup>
  ```bash cURL — Attach media theme={null}
  curl -X POST https://api.synq.app/api/v1/pim/media \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "product_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "url": "https://cdn.example.com/wool-sweater-front.jpg",
      "alt_text": "Classic Wool Sweater — front view",
      "sort_order": 1
    }'
  ```
</CodeGroup>