# Merchkit API

Merchkit is an AI-native PIM (Product Information Management) system. The core
object is a **product** (and also assets, vendors, and categories) — each with
dynamic **attributes**. Attributes can be channel-scoped, and **completeness is
per-channel**: a product can be complete for one channel and incomplete for
another.

## Authentication

Send your workspace API key as a bearer token:

    Authorization: Bearer mk_live_...

One key maps to exactly one workspace. Keys carry scopes; read keys cannot
perform writes. Available scopes:

- `read:products`: List and read products, assets, vendors, sources, and merch.
- `write:products`: Create and update products and their attribute values.
- `delete:products`: Delete products.
- `read:attributes`: List and read attribute definitions.
- `write:attributes`: Create, update, and delete attribute definitions.
- `write:attribute_values`: Set attribute values on entities.
- `read:views`: List and read saved grid views.
- `write:views`: Create and update grid views.
- `read:vendors`: List and read vendor records.
- `write:vendors`: Create and update vendor records.
- `read:categories`: List and read categories.
- `write:categories`: Create and update categories.
- `read:channels`: Read the available channel catalog.
- `read:completeness`: Check per-channel completeness for entities.
- `read:history`: Read entity history and the account change feed.
- `read:jobs`: Poll asynchronous job status.

## Base URL & spec

- Base URL: `/api/v1`
- OpenAPI: `/api/v1/openapi`

## MCP (operate from Claude and other agents)

- Remote MCP endpoint (Streamable HTTP): `/api/mcp`
- Authenticate with the same key: `Authorization: Bearer mk_live_...`
- Tools mirror this API: search_products, get_product, list_attributes,
  get_completeness, get_references, get_history, list_channels, get_job (reads);
  create_product, set_attribute_values, set_parent, delete_product (writes).
- **Write tools take `confirm`**: call with `confirm` omitted/false to get a
  preview (a diff, no change), then again with `confirm: true` to apply.
- A read-only key cannot call write tools (enforced by scope).

## Key endpoints

- `GET /v1/products` — list/search products (filter DSL, sort, pagination)
- `GET /v1/products/{id}` — full product detail
- `POST /v1/products` — create a product (optionally a variant via parent_entity)
- `PATCH /v1/products/{id}/attributes` — set attribute values (enrichment)
- `GET /v1/products/{id}/completeness?channel=` — per-channel completeness
- `GET /v1/attributes?entity_type=product&channel=` — attribute definitions
- `POST /v1/attributes` / `PATCH /v1/attributes/{key}` — create/update attribute
  definitions, incl. AI generation config (set `aiGenerated` + `customInstructions`;
  `selectedTools: ["includeWebSearch"]` for live web research, `["includeDataSources"]`
  for scraped sources). For product attributes, `inheritanceMode` shares a value across a
  variant family (`inherit_from_parent` onto variants, or `rollup_from_children` onto the parent)
- `/v1/attribute-classes` — cell-disabling rules; `/v1/grid-views` — saved views (create/update)
- `GET /v1/jobs/{id}` — poll an async operation

## How to work with this API (read this)

- **Identify products by their primary attribute (e.g. SKU)** when talking to a
  user; use the UUID `id` for API calls.
- **To enrich a product, `PATCH /products/{id}/attributes`** — do NOT recreate
  the product to change a value.
- **Completeness is channel-specific: always pass `?channel=`.** A product can
  be complete for one channel and not another.
- **Find products missing an attribute** with the `blank` operator, e.g.
  `?filter[description][blank]=true`. Use `notBlank` for the inverse.
- **Reference attributes return `{ entityId, entityType, label }`** summaries,
  not raw UUIDs. Fetch full detail via `GET /products/{id}`.
- **List endpoints are paginated** — `limit` (default 50, max 200) + `offset`;
  read `pagination.has_more`.
- **Channels are read-only and global** — you cannot create them via the API.
- **Deletes are disabled during the beta** — `DELETE` endpoints return `403`
  and there is no delete tool in MCP; destructive actions are enabled later.
- **Errors are machine-readable**: each carries `code`, `is_retriable`,
  `retry_after_seconds`, and `field_errors[].acceptable_values` for self-correction.

## Filtering

`filter[<attributeKey>][<operator>]=<value>`, combined with `filter_join=AND|OR`.
Operators: contains, equals, notEquals, notContains, startsWith, endsWith,
blank, notBlank, greaterThan, lessThan, greaterThanOrEqual, lessThanOrEqual.