A1 Yandex KIT — Catalog

Communication

Before producing any user-facing message, read and apply

../a1-yandex-kit/references/merchant-communication.md

completely.

Covers the catalog domain of the Yandex KIT e-commerce API — tags: Товары, Категории товаров, Характеристики товаров, Видео, Коллекции, Контекстные коллекции, Бейджи. In KIT's model the variant (

/v1/variants

) is the sellable unit carrying SKU, prices and per-warehouse stocks, and a product (

/v1/products

) groups variants, so most «товар» operations act on variants. A variant carries two distinct identifiers:

product_id

and

product_card_id

(карточка товара) — the card-scoped endpoints (

/v1/products/cards/{product_card_id}/similar...

and collection card management, «Добавление/Удаление карточек») take

product_card_id

, never a product id; read it from the variant first. Variant documents (инструкции, сертификаты, паспорта) live under

/v1/variants/{id}/attachments

: upload the file via

POST /v1/files

first, then attach it by

file_id

; the title must not contain

, and

display_sequence

must be unique per variant (an occupied value returns 409 — nothing is reordered automatically). Mind the content types:

UpdateVariant

UpdateCategory

UpdateCharacteristic

and

UpdateVariantAttachment

use JSON Merge Patch (

application/merge-patch+json

— send only the fields to change;

null

clears only the fields the schema marks nullable, see the

a1-yandex-kit

skill), while the other updates are plain

application/json

For catalog-wide syncs prefer the bulk endpoints over per-variant PATCHes:

POST /v1/variants/prices/bulk_update

and

POST /v1/variants/stocks/bulk_update

take up to 5000 items each and are synchronous and atomic — one invalid item (unknown or archived variant, a variant repeated in the batch, a malformed price) rejects the whole request with 400 and applies nothing, listing every offender in

errors

. In a price item both fields are optional: omit a key to keep the current value, send

null

to reset it (resetting

price

works only on unpublished variants).

Product videos are a separate tag: use

POST /v1/videos

for a local file (

multipart/form-data

) or

POST /v1/videos/from_url

for a public link. Both accept videos up to 100 MB in mp4/mov/webm/avi/flv and deduplicate by content. Poll

GET /v1/videos/{video_id}

—

UPLOADED

→

PROCESSING

→

READY

, at most once every 5 seconds — and link only a ready video. A variant accepts at most one video and only alongside at least one image in the same

media

list. Sending

media

UpdateVariant

replaces the whole list, so preserve every existing image and untouched entry. Characteristics carry two extras beyond the values themselves: groups (

/v1/characteristics/groups

, ordered by

display_sequence

) and colors (

/v1/characteristics/colors

), where

UpdateCharacteristicColor

recolors an existing value addressed by the value itself — there is no id — accepting a hex code or the special

multicoloured

transparent

For authentication (

Authorization: Bearer <token>

), the base URL (

https://api.kit.yandex.net

, all paths under

/v1/

), the 3 rps rate limit and the

{code, message, trace_id}

error contract, see the

a1-yandex-kit

skill.

Workflow

Run the bundled scripts from this skill's directory — they are self-contained (Node.js >= 20, builtins + a vendored validator, no

npm install

, no network).

Search for the operation you need:

bash

node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]

Matches operation ids, paths, tags and the Russian summaries/descriptions, e.g.

node scripts/search_docs.mjs "создать товар"

Inspect the full contract of one operation — path/query parameters plus the fully dereferenced request/response schemas:
bash
```
node scripts/search_docs.mjs --operation CreateProduct
```

Validate a drafted request body offline before sending anything:

bash

node scripts/validate.mjs --operation CreateProduct --body '<json>'
# or: node scripts/validate.mjs --operation CreateProduct --body-file body.json

Prints

VALID

(exit 0) or the list of schema violations (exit 1).

Execute the operation:
- prefer the matching
```
mcp-yandex-kit
```
  MCP tool from «Related MCP tools» below (e.g.
```
create_product
```
  ,
```
update_variant
```
  );
- any operation without a dedicated tool: the
```
kit_request
```
  MCP tool — it validates the body against the same schema before sending;
- or plain HTTP:
```
curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
```
  (mind the 3 rps limit).

Endpoints (71 operations)

Товары

Method	Path	OperationId	Summary (RU)
GET	`/v1/products`	`GetProducts`	Получение списка продуктов
POST	`/v1/products`	`CreateProduct`	Создание нового продукта
GET	`/v1/products/{id}`	`GetProductById`	Получение продукта по ID
PATCH	`/v1/products/{id}`	`UpdateProduct`	Обновление продукта
GET	`/v1/products/cards/{product_card_id}/similar`	`GetSimilarProductCardIDs`	Получение списка похожих карточек товара.
POST	`/v1/products/cards/{product_card_id}/similar/add`	`AddSimilarProductCards`	Добавление похожих карточек товара
POST	`/v1/products/cards/{product_card_id}/similar/remove`	`DeleteSimilarProductCards`	Удаление похожих карточек товара
GET	`/v1/variants`	`GetVariants`	Получение списка товаров
POST	`/v1/variants`	`CreateVariant`	Создание нового товара
GET	`/v1/variants/{id}`	`GetVariantById`	Получение товара по ID
PATCH	`/v1/variants/{id}`	`UpdateVariant`	Обновление товара
DELETE	`/v1/variants/{id}`	`DeleteVariant`	Безвозвратное удаление архивного товара
POST	`/v1/variants/{id}/archive`	`ArchiveVariant`	Архивирование товара
POST	`/v1/variants/{id}/unarchive`	`UnarchiveVariant`	Восстановление товара из архива
GET	`/v1/variants/{id}/external_ids`	`GetVariantExternalIDs`	Получение внешних идентификаторов товара
PUT	`/v1/variants/{id}/external_ids/{system_type}`	`SetVariantExternalID`	Установка внешнего идентификатора
DELETE	`/v1/variants/{id}/external_ids/{system_type}`	`DeleteVariantExternalID`	Удаление внешнего идентификатора
GET	`/v1/variants/{id}/attachments`	`GetVariantAttachments`	Получение документов товара
POST	`/v1/variants/{id}/attachments`	`CreateVariantAttachment`	Прикрепление документа к товару
PATCH	`/v1/variants/{id}/attachments/{file_id}`	`UpdateVariantAttachment`	Обновление документа товара
DELETE	`/v1/variants/{id}/attachments/{file_id}`	`DeleteVariantAttachment`	Открепление документа от товара
POST	`/v1/variants/stocks/bulk_update`	`BulkUpdateStocks`	Массовое обновление остатков
POST	`/v1/variants/prices/bulk_update`	`BulkUpdatePrices`	Массовое обновление цен

Категории товаров

Method	Path	OperationId	Summary (RU)
GET	`/v1/categories`	`GetCategories`	Получение списка категорий
POST	`/v1/categories`	`CreateCategory`	Создание новой категории
GET	`/v1/categories/{id}`	`GetCategoryById`	Получение категории по ID
PATCH	`/v1/categories/{id}`	`UpdateCategory`	Обновление категории
POST	`/v1/categories/{id}/archive`	`ArchiveCategory`	Архивирование категории
POST	`/v1/categories/{id}/unarchive`	`UnarchiveCategory`	Восстановление категории из архива

Характеристики товаров

Method	Path	OperationId	Summary (RU)
GET	`/v1/characteristics`	`GetCharacteristics`	Получение списка характеристик
POST	`/v1/characteristics`	`CreateCharacteristic`	Создание новой характеристики
GET	`/v1/characteristics/{id}`	`GetCharacteristicById`	Получение характеристики по ID
PATCH	`/v1/characteristics/{id}`	`UpdateCharacteristic`	Обновление характеристики
POST	`/v1/characteristics/{id}/archive`	`ArchiveCharacteristic`	Архивирование характеристики
POST	`/v1/characteristics/{id}/unarchive`	`UnarchiveCharacteristic`	Восстановление характеристики из архива
GET	`/v1/characteristics/groups`	`GetCharacteristicGroups`	Получение списка групп характеристик
POST	`/v1/characteristics/groups`	`CreateCharacteristicGroup`	Создание группы характеристик
GET	`/v1/characteristics/groups/{id}`	`GetCharacteristicGroupById`	Получение группы характеристик по ID
PATCH	`/v1/characteristics/groups/{id}`	`UpdateCharacteristicGroup`	Обновление группы характеристик
DELETE	`/v1/characteristics/groups/{id}`	`DeleteCharacteristicGroup`	Удаление группы характеристик
GET	`/v1/characteristics/colors`	`GetCharacteristicColors`	Получение списка цветов
PATCH	`/v1/characteristics/colors`	`UpdateCharacteristicColor`	Обновление hex-кода для значения цветовой характеристики

Видео

Method	Path	OperationId	Summary (RU)
GET	`/v1/videos`	`GetVideos`	Получение списка видео
POST	`/v1/videos`	`UploadVideo`	Загрузка видео
POST	`/v1/videos/from_url`	`UploadVideoFromUrl`	Загрузка видео по ссылке
GET	`/v1/videos/{video_id}`	`GetVideoById`	Получение видео по идентификатору

Коллекции

Method	Path	OperationId	Summary (RU)
GET	`/v1/collections/{collection_id}`	`GetCollectionById`	Получение коллекции по ID
PATCH	`/v1/collections/{collection_id}`	`UpdateCollection`	Обновление коллекции
DELETE	`/v1/collections/{collection_id}`	`DeleteCollectionById`	Удаление коллекции
POST	`/v1/collections/{collection_id}/cards/add`	`AddCardsToCollection`	Добавление карточек в статическую коллекцию
POST	`/v1/collections/{collection_id}/cards/remove`	`RemoveCardsFromCollection`	Удаление карточек из статической коллекции
GET	`/v1/collections/{collection_id}/cards/manual-order`	`GetCollectionCardsManualOrder`	Получение ручного порядка карточек коллекции
POST	`/v1/collections/{collection_id}/cards/move`	`MoveCollectionCards`	Перемещение карточек в статической коллекции
GET	`/v1/collections`	`GetCollections`	Получение списка коллекций
POST	`/v1/collections`	`CreateCollection`	Создание коллекции
GET	`/v1/collections/{collection_id}/variants`	`GetVariantsByCollectionId`	Получение ID товаров коллекции по ID

Контекстные коллекции

Method	Path	OperationId	Summary (RU)
GET	`/v1/context-collections`	`GetContextCollections`	Получение списка контекстных коллекций
POST	`/v1/context-collections`	`CreateContextCollection`	Создание контекстной коллекции
GET	`/v1/context-collections/{id}`	`GetContextCollectionById`	Получение контекстной коллекции по ID
PATCH	`/v1/context-collections/{id}`	`UpdateContextCollection`	Обновление контекстной коллекции
DELETE	`/v1/context-collections/{id}`	`DeleteContextCollection`	Удаление контекстной коллекции

Бейджи

Method	Path	OperationId	Summary (RU)
GET	`/v1/badges/{badge_id}`	`GetBadgeById`	Получение бейджа по уникальному идентификатору
PATCH	`/v1/badges/{badge_id}`	`UpdateBadge`	Обновление бейджа
DELETE	`/v1/badges/{badge_id}`	`DeleteBadgeById`	Удаление бейджа
GET	`/v1/badges`	`GetBadges`	Получение списка бейджей
POST	`/v1/badges`	`CreateBadge`	Создание бейджа
GET	`/v1/badges/{badge_id}/variants`	`GetBadgeVariantIDs`	Получение уникальных идентификаторов товаров бейджа
GET	`/v1/badges/{badge_id}/categories`	`GetBadgeCategoryIDs`	Получение идентификаторов категорий бейджа
GET	`/v1/badges/{badge_id}/collections`	`GetBadgeCollectionIDs`	Получение идентификаторов коллекций бейджа
POST	`/v1/badges/{badge_id}/objects/add`	`AddBadgeObjects`	Добавление объектов в бейдж
POST	`/v1/badges/{badge_id}/objects/remove`	`RemoveBadgeObjects`	Удаление объектов из бейджа

Related MCP tools

Curated

mcp-yandex-kit

tools for these tags (the server also exposes the meta trio —

search_operations

get_operation_schema

kit_request

— reaching all 162 operations):

```
list_products
```
— List products of the store (paginated).
```
get_product
```
— Get a single product by its ID, including its category bindings.
```
create_product
```
— Create a new product.
```
update_product
```
— Update an existing product (plain JSON PATCH, not merge-patch).
```
list_variants
```
— List variants (sellable items / SKUs) of the store, with optional filters (paginated).
```
get_variant
```
— Get a single variant by its ID (name, SKU, pricing, stocks, media, status).
```
create_variant
```
— Create a new variant (sellable item) under an existing product.
```
update_variant
```
— Update an existing variant via JSON Merge Patch: send only the fields to change (e.g. pricing or stocks).
```
bulk_update_prices
```
— Update prices of up to 5000 variants in one synchronous, atomic request — the fast path for syncing a whole catalog instead of calling update_variant per item.
```
variant_action
```
— Archive a variant (soft delete: status becomes ARCHIVED, item is hidden from the storefront but restorable) or unarchive it (status becomes HIDDEN; publish it afterwards via update_variant).
```
list_categories
```
— List product categories of the store (paginated).
```
get_category
```
— Get a single product category by its ID.
```
create_category
```
— Create a new product category.
```
update_category
```
— Update an existing category via JSON Merge Patch: send only the fields to change.
```
category_action
```
— Archive a category (soft delete: hidden from the storefront, restorable) or unarchive it.
```
list_characteristics
```
— List product characteristics (paginated).
```
get_characteristic
```
— Get one product characteristic by ID.
```
create_characteristic
```
— Create a product characteristic.
```
update_characteristic
```
— Update a product characteristic.
```
list_characteristic_groups
```
— List product characteristic groups (paginated).
```
get_characteristic_group
```
— Get one product characteristic group by ID.
```
create_characteristic_group
```
— Create a product characteristic group.
```
update_characteristic_group
```
— Update a product characteristic group.
```
list_characteristic_colors
```
— List the color values of the store's characteristics with their hex codes (paginated).
```
update_characteristic_color
```
— Set the hex code of a color characteristic value.
```
list_videos
```
— List product videos of the store (paginated), oldest upload first.
```
get_video
```
— Get a single video by its ID with the current processing status.
```
upload_video
```
— Upload a product video via multipart/form-data and queue it for processing.
```
upload_video_from_url
```
— Upload a product video by public link and queue it for processing — use it instead of upload_video when the file lives on the web rather than on this machine.
```
list_collections
```
— List collections of the store (paginated).
```
get_collection
```
— Get a single collection by its ID (title, slug, status, type, SEO fields).
```
create_collection
```
— Create a new collection.
```
update_collection
```
— Update an existing collection (plain JSON PATCH; only the provided fields are changed).
```
delete_collection
```
— Permanently delete a collection by its ID.
```
manage_collection_cards
```
— Add product cards to a STATIC collection or remove them from it.

Контекстные коллекции and Бейджи have no dedicated tools — reach them through

search_operations

kit_request

a1-yandex-kit-catalog

NPX Install

Tags

SKILL.md Content