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

# Merchandising & Content Toolkit API overview

> Authentication, public endpoints, and admin route reference for Merchandising & Content Toolkit.

# Merchandising & Content Toolkit API overview

## Authentication

Authenticated admin endpoints require a Shopify session token sent as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer <shopify-session-token>" \
  "${APP_ORIGIN:?Set APP_ORIGIN}/api/collections"
```

The token is obtained via `window.shopify.idToken()` (App Bridge v4) and validated server-side. The shop is always derived from the authenticated session. Health endpoints are public; public storefront routes use per-experiment tokens; OAuth and webhooks have their own guards.

## Public endpoints

* `GET /api/health` and `GET /healthz` — no authentication; return build identity and database/Redis status.
* `GET /api/public/market-ranking` — App-proxy HMAC market ranking.
* `GET /api/public/merchandising/ab-tests/:id/assignment` and `POST /api/public/merchandising/ab-tests/:id/metrics` — storefront A/B assignment and metrics, gated by the experiment token and the Advanced entitlement.
* `GET /privacy` and `GET /terms` — HTTP 301 redirects to the shared docs-site policy pages.
* `/marketing`, `/features/*`, `/pricing`, `/cookies`, `/accessibility`, `/support`, `/sitemap.xml`, `/robots.txt` — public marketing, pricing, and policy pages.

## Admin endpoints

### Collections, products, and pages

* `GET /api/collections` — list collections with pagination (`first`, `after`, `query`).
* `GET /api/collections/search` — search collections by title.
* `GET /api/collections/:id` — get a collection with its products.
* `GET /api/products` and `GET /api/products/search` — list and search products.
* `GET /api/pages` — list pages.

### Sorting rules and jobs

* `GET /api/sorting-rules`, `POST /api/sorting-rules`, `GET /api/sorting-rules/:id`, `PUT /api/sorting-rules/:id`, `DELETE /api/sorting-rules/:id`.
* `POST /api/sorting-rules/:id/run` — enqueue a background sorting job.
* `GET /api/sorting-jobs` and `GET /api/sorting-jobs/:id` — job history and details.

### Hierarchy and content

* `GET /api/hierarchy` and `POST /api/hierarchy/save` — read and update the collection tree.
* `GET /api/content/:resourceType/:resourceId` and `POST /api/content/:resourceType/:resourceId` — read and save content blocks, where `resourceType` is `product`, `collection`, or `page`.

### Metafield definition maintenance

* `GET /api/metafield-definitions` — read-only health report.
* `POST /api/metafield-definitions/reconcile` — repair Shopify/local definition drift.

### Billing

* `GET /api/billing` — current plan, entitlements, and domains.
* `GET /api/billing/plans` — annotated plan list.
* `POST /api/billing/select` — request a plan via the Billing API (paid plans return a confirmation URL; `free` cancels any active charge).
* `GET /api/billing/confirmed` — reconcile after Shopify confirmation.

### Merchandising (Advanced-gated)

* `GET /api/merchandising/ga4` and `POST /api/merchandising/ga4` — GA4 integration config (requires `ga4Integration`).
* `POST /api/merchandising/ab-tests` — create an A/B experiment.
* `POST /api/merchandising/ai-tags/generate` and `PUT /api/merchandising/ai-tags` — generate and persist urgency tags (requires `aiSentimentUrgencyTags`, Pro+).

### Advanced tools

* `GET /api/analytics` — advanced analytics dashboard summary.
* `GET /api/dynamic-collections`, `POST /api/dynamic-collections`, `POST /api/dynamic-collections/:id/run` — dynamic collection rules.
* `GET /api/merchant-webhooks` and `POST /api/merchant-webhooks` — signed outbound webhooks (secrets omitted in responses).
* `GET /api/privacy-exports` and `GET /api/privacy-exports/:id/download` — list and download customer data exports.

## Dashboard and setup

* `GET /api/dashboard`, `POST /api/dashboard/skip-setup` — home metrics and setup skip.
* `GET /api/setup-status`, `GET /api/setup-status/themes`, `GET /api/setup-status/themes/:themeId`, `POST /api/setup-status/skip` — onboarding progress and theme choices.

## Error responses

All errors return JSON:

```json theme={null}
{
  "error": {
    "message": "Description of the error"
  }
}
```

Common status codes: `200`/`201` success, `400` validation, `401` unauthorized, `402` missing entitlement, `404` not found, `500` internal error, `503` service unavailable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.