A1 Yandex KIT Skills

Communication

Before producing any user-facing message, read and apply

references/merchant-communication.md

completely.

Yandex KIT (kit.yandex.ru, beta) is Yandex's e-commerce store builder — effectively a Russian Shopify. Its REST API is a server-to-server layer for syncing catalog, stocks and prices and for managing orders between a merchant's backend and the platform. The official docs are in Russian; the full OpenAPI spec (162 operations) is bundled with this skill in

data/kit_v1.json.gz

and searchable offline with the scripts below.

API essentials

Base URL:
```
https://api.kit.yandex.net
```
, every path is prefixed with
```
/v1/
```
.
Auth:
```
Authorization: Bearer <token>
```
(plain HTTP Bearer, not OAuth). The token is generated in the merchant cabinet: Settings → API → Generate token — it is shown only once, store it securely and generate a new one if lost.
Rate limit: 3 requests per second per store, no quota headers. Exceeding it returns code
```
LIMIT_EXCEEDED
```
with HTTP 400 (not 429) — throttle client-side and detect the error by its
```
code
```
, not by the status.

Error contract: every error is JSON

{"code", "message", "trace_id"}

. Codes:

AUTHENTICATION_ERROR

(401),

FORBIDDEN_ERROR

(403),

VALIDATION_ERROR

(400),

LIMIT_EXCEEDED

(400),

UNSUPPORTED_MEDIA_TYPE

(415),

NOT_FOUND

(404),

CONFLICT

(409),

UNKNOWN_ERROR

(500). Quote

trace_id

when contacting support.

Datetimes: everything is UTC.
No sandbox: production only — prefer read-only calls while exploring and double-check every write.
Pagination: list endpoints take
```
page
```
+
```
per_page
```
(max 100) query parameters.
Content types: request bodies are
```
application/json
```
, except the 5 operations that use JSON Merge Patch (
```
application/merge-patch+json
```
):
```
UpdateCategory
```
,
```
UpdateCharacteristic
```
,
```
UpdateVariant
```
,
```
UpdateVariantAttachment
```
,
```
UpdateWarehouse
```
— send only the fields to change.
```
null
```
clears a field only where the schema marks it nullable — of these, that is just
```
parent_id
```
and
```
file_id
```
of
```
UpdateCategory
```
; elsewhere
```
null
```
fails validation (
```
validate.mjs
```
below will catch it).
```
POST /v1/files
```
(
```
UploadFile
```
) and
```
POST /v1/videos
```
(
```
UploadVideo
```
) are
```
multipart/form-data
```
.
Bulk writes:
```
BulkUpdatePrices
```
and
```
BulkUpdateStocks
```
take up to 5000 items per request and are atomic — a single invalid item rejects the whole batch (400) and applies nothing. Prefer them over per-variant updates for catalog syncs.

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 bundled
```
mcp-yandex-kit
```
  MCP server: a curated tool when one exists (see the domain skills), otherwise the meta trio below;
- 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).

Domain skills

Prefer the focused skill when the task clearly belongs to one domain — each bundles the same scripts and data, plus the endpoint tables of its tags:

```
a1-yandex-kit-catalog
```
— products, variants (SKUs, prices, stocks, bulk price/stock sync), categories, characteristics (groups, colors), videos, collections, context collections, badges.
```
a1-yandex-kit-orders
```
— orders, customers, gift cards, additional services (addons).
```
a1-yandex-kit-promotions
```
— discounts, promo codes, promocode groups, gifts.
```
a1-yandex-kit-store
```
— store profile, warehouses, users, geo, files, redirects, blog/news, alerts.
```
a1-yandex-kit-webhooks
```
— webhooks: order events, HTTPS callbacks, signing secret.

Related MCP tools

The bundled

mcp-yandex-kit

MCP server exposes 84 tools. Curated tools cover the everyday catalog/orders/promotions/store/webhooks workflows (they are listed in the domain skills); the meta trio below reaches all 162 operations:

```
search_operations
```
— Search the full catalog of all 162 Yandex KIT API operations by keyword.
```
get_operation_schema
```
— Get full metadata for one KIT API operation by operationId: HTTP method, path, path/query parameters, request content type, pagination info, and the fully dereferenced JSON schemas of the request body and response.
```
kit_request
```
— Escape hatch that executes ANY of the 162 Yandex KIT API operations by operationId, including operations without a dedicated tool.

a1-yandex-kit

NPX Install

Tags

SKILL.md Content