Справочник API

BatchError#

Пример

{
    "code": "not_found",
    "message": "Объект не найден"
}

BatchOperation#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "data": {
        "available": false
    },
    "id": "def",
    "op": "patch"
}

BatchRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "operations": [
        {
            "data": {
                "title": "Заметка",
                "type": "text"
            },
            "id": "abc",
            "op": "put"
        },
        {
            "data": {
                "available": false
            },
            "id": "def",
            "op": "patch"
        },
        {
            "id": "old-1",
            "op": "delete"
        }
    ]
}

BatchResponse#

Пример

{
    "results": [
        {
            "id": "abc",
            "ok": true,
            "status": "queued"
        },
        {
            "error": {
                "code": "not_found",
                "message": "Объект не найден"
            },
            "id": "def",
            "ok": false
        }
    ]
}

BatchResult#

Пример

{
    "id": "abc",
    "ok": true,
    "status": "queued"
}

EndUserIds#

Идентификаторы конечного пользователя (ТЗ §8): хотя бы одно поле.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "anonymous_id": "b7f3c9",
    "user_id": "u-42"
}

ErrorDetail#

Ошибка одного поля или параметра.

Пример

{
    "code": "invalid_url",
    "field": "media[0].url",
    "message": "допустим только адрес https"
}

ErrorInfo#

ErrorResponse#

Пример

{
    "error": {
        "code": "validation_failed",
        "details": [
            {
                "code": "invalid_url",
                "field": "media[0].url",
                "message": "допустим только адрес https"
            }
        ],
        "message": "Поля не прошли проверку"
    }
}

EventIn#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "id": "evt-1001",
    "item": "v-123",
    "occurred_at": "2026-09-14T12:00:00.250Z",
    "position": 3,
    "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W3",
    "surface": "feed",
    "type": "watch",
    "user": {
        "user_id": "u-42"
    },
    "value": 184
}

EventRejection#

EventTypeOut#

EventTypesResponse#

Тип: EventTypeOut[]

Пример

[
    {
        "code": "view",
        "dedup_window_sec": 86400,
        "hides_item": false,
        "is_active": true,
        "is_goal": false,
        "is_impression": false,
        "is_open": true,
        "is_purchase": false,
        "mode": "fact",
        "suppress_similar_days": 0,
        "title": "Открытие",
        "value_kind": "none",
        "weight": 0.2
    }
]

EventsRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "events": [
        {
            "id": "evt-1001",
            "item": "v-123",
            "occurred_at": "2026-09-14T12:00:00Z",
            "position": 0,
            "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W3",
            "surface": "feed",
            "type": "impression",
            "user": {
                "user_id": "u-42"
            }
        },
        {
            "id": "evt-1002",
            "item": "v-123",
            "occurred_at": "2026-09-14T12:00:03Z",
            "position": 0,
            "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W3",
            "surface": "feed",
            "type": "view",
            "user": {
                "user_id": "u-42"
            }
        },
        {
            "id": "evt-1003",
            "item": "v-123",
            "occurred_at": "2026-09-14T12:03:07.250Z",
            "type": "watch",
            "user": {
                "user_id": "u-42"
            },
            "value": 184
        },
        {
            "id": "evt-1004",
            "item": "v-77",
            "type": "like",
            "user": {
                "anonymous_id": "b7f3c9"
            },
            "value": 1
        }
    ]
}

EventsResponse#

Пример

{
    "accepted": 998,
    "duplicates": 1,
    "rejected": [
        {
            "code": "unknown_item",
            "id": "evt-1018",
            "index": 17
        }
    ]
}

FeedItem#

FeedRequest#

Лента: первая страница (offset = 0) строит новую выдачу, следующие берутся из снимка выдачи.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "exclude": [
        "v-17"
    ],
    "filters": {
        "category": {
            "in": [
                "sport",
                "travel"
            ]
        }
    },
    "limit": 24,
    "offset": 0,
    "user": {
        "anonymous_id": "b7f3c9",
        "user_id": "u-42"
    }
}

FeedResponse#

Пример

{
    "has_more": true,
    "identity": "user",
    "items": [
        {
            "id": "v-123",
            "reason": "interest",
            "score": 0.8123
        },
        {
            "id": "v-77",
            "reason": "trending",
            "score": 0.6402
        }
    ],
    "mode": "personal",
    "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W3"
}

FrameOut#

HealthResponse#

Пример

{
    "status": "ok"
}

ItemDeleteResponse#

Пример

{
    "deleted": true,
    "id": "abc"
}

ItemDetail#

Объект с результатами анализа; transcript, frames, search_chunks — только по include.

Пример

{
    "author": "channel-42",
    "available": true,
    "deleted": false,
    "description": "Обзор городских моделей",
    "id": "v-123",
    "media": [
        {
            "duration_sec": 312.48,
            "height": 1080,
            "kind": "video",
            "position": 0,
            "status": "ready",
            "url": "https://cdn.example.ru/v-123.mp4",
            "width": 1920
        }
    ],
    "origin": "api",
    "processing": {
        "embedding": "done",
        "prepare": "done",
        "speech": "done",
        "summary": "done",
        "vision": "done"
    },
    "properties": {
        "category": "sport"
    },
    "published_at": "2026-09-14T12:00:00Z",
    "status": "ready",
    "summary": {
        "age_rating": "0+",
        "description": "Обзор городских велосипедов: рама, передачи, тормоза.",
        "entities": [
            {
                "name": "Москва",
                "type": "place"
            }
        ],
        "language": "ru",
        "moderation": {
            "categories": {
                "adult": 0,
                "drugs": 0,
                "extremism": 0,
                "gambling": 0,
                "gore": 0,
                "hate": 0,
                "self_harm": 0,
                "spam": 0.01,
                "violence": 0,
                "weapons": 0
            },
            "evidence": [],
            "level": "none"
        },
        "summary": "Ведущий сравнивает городские велосипеды и объясняет, как подобрать раму по росту.",
        "tags": [
            "велосипед",
            "обзор",
            "рама",
            "передачи",
            "тормоза"
        ],
        "topics": [
            "велосипеды",
            "городской транспорт",
            "выбор снаряжения"
        ]
    },
    "title": "Как выбрать велосипед",
    "transcript": [
        {
            "language": "ru",
            "media_position": 0,
            "segments": [
                {
                    "end": 4.8,
                    "start": 1.2,
                    "text": "Добрый день! Сегодня расскажем, как выбрать городской велосипед."
                }
            ],
            "text": "Добрый день! Сегодня расскажем, как выбрать городской велосипед.",
            "timestamps": "model"
        }
    ],
    "type": "video",
    "updated_at": "2026-09-14T12:06:41.512Z",
    "url": "https://example.ru/v/v-123"
}

ItemListEntry#

ItemListResponse#

Пример

{
    "items": [
        {
            "available": true,
            "deleted": false,
            "id": "abc",
            "status": "ready",
            "updated_at": "2026-09-14T12:00:00.123Z"
        }
    ]
}

ItemPatchRequest#

Частичное обновление: переданные поля заменяются, null очищает поле, кроме media и available; type не меняется.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "available": false
}

ItemPutRequest#

Объект целиком. Непереданные поля очищаются.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "author": "channel-42",
    "available": true,
    "description": "Обзор городских моделей",
    "media": [
        {
            "kind": "video",
            "url": "https://cdn.example.ru/abc.mp4",
            "version": "1"
        }
    ],
    "properties": {
        "category": "sport"
    },
    "published_at": "2026-09-14T12:00:00Z",
    "title": "Как выбрать велосипед",
    "type": "video",
    "url": "https://example.ru/v/abc"
}

ItemWriteResponse#

Пример

{
    "available": true,
    "deleted": false,
    "id": "abc",
    "processing": {
        "embedding": "queued",
        "prepare": "queued",
        "speech": "queued",
        "summary": "queued",
        "vision": "queued"
    },
    "status": "queued"
}

MediaIn#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "kind": "video",
    "url": "https://cdn.example.ru/abc.mp4",
    "version": "1"
}

MediaOut#

Пример

{
    "duration_sec": 312.48,
    "height": 1080,
    "kind": "video",
    "position": 0,
    "status": "ready",
    "url": "https://cdn.example.ru/abc.mp4",
    "width": 1920
}

Moderation#

NetworkChild#

NetworkCompany#

NetworkData#

Пример

{
    "age_group": "25_34",
    "checked_at": "2026-09-24T10:00:00Z",
    "children": [
        {
            "age_group": "3_6"
        }
    ],
    "city": "нижний новгород",
    "company": {
        "industry": "Торговля",
        "region": "Москва",
        "type": "legal"
    },
    "country": "RU",
    "gender": "female",
    "gender_confidence": 0.95,
    "interests": [
        {
            "path": "Дом > Ремонт",
            "sensitive": false,
            "share": 0.6,
            "topic_id": 11
        }
    ],
    "purchases": [
        {
            "category_id": 5,
            "path": "Дом > Мебель",
            "segment": "mid"
        }
    ],
    "region": "нижегородская область",
    "status": "found"
}

NetworkInterest#

NetworkPurchase#

OrderIn#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "items": [
        {
            "item": "sku-1",
            "price": 990,
            "quantity": 2
        },
        {
            "item": "sku-2",
            "price": 450
        },
        {
            "item": "sku-new",
            "properties": {
                "brand": "Дом"
            },
            "title": "Кружка керамическая"
        }
    ],
    "occurred_at": "2026-09-14T12:00:00Z",
    "order_id": "A-100500",
    "user": {
        "user_id": "u-42"
    }
}

OrderLineIn#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

OrderLineRejection#

OrderResponse#

Пример

{
    "accepted": 2,
    "order_id": "A-100500",
    "rejected": [
        {
            "code": "unknown_item",
            "index": 2,
            "item": "sku-x"
        }
    ]
}

OrdersBatchRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "orders": [
        {
            "items": [
                {
                    "item": "sku-1",
                    "price": 990,
                    "quantity": 2
                },
                {
                    "item": "sku-2",
                    "price": 450
                }
            ],
            "occurred_at": "2026-03-02T09:15:00Z",
            "order_id": "A-100500",
            "user": {
                "user_id": "u-42"
            }
        },
        {
            "items": [
                {
                    "item": "sku-2",
                    "price": 450,
                    "quantity": 1
                },
                {
                    "item": "sku-archive-7",
                    "price": 1290,
                    "title": "Термос 0,5 л"
                }
            ],
            "occurred_at": "2026-03-05T18:40:00Z",
            "order_id": "A-100501",
            "user": {
                "user_id": "u-43"
            }
        },
        {
            "occurred_at": "2026-02-11T10:00:00Z",
            "order_id": "A-100377",
            "status": "cancelled",
            "user": {
                "user_id": "u-42"
            }
        }
    ]
}

OrdersBatchResponse#

Пример

{
    "results": [
        {
            "accepted": 3,
            "index": 0,
            "ok": true,
            "order_id": "A-1",
            "rejected": []
        },
        {
            "error": {
                "code": "validation_failed",
                "details": [
                    {
                        "code": "too_old",
                        "field": "occurred_at",
                        "message": "заказ старше 730 дней"
                    }
                ],
                "message": "Поля не прошли проверку"
            },
            "index": 1,
            "ok": false,
            "order_id": "A-2"
        }
    ]
}

OrdersBatchResult#

Processing#

Состояние публичных шагов анализа.

Пример

{
    "embedding": "done",
    "prepare": "done",
    "speech": "running",
    "summary": "queued",
    "vision": "done"
}

ProfileBatchRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "profiles": [
        {
            "birth_year": 1997,
            "city": "Казань",
            "gender": "female",
            "interests": [
                "горные велосипеды",
                "фотография"
            ],
            "user": {
                "user_id": "u-42"
            }
        },
        {
            "age": 35,
            "followed_authors": [
                "channel-7"
            ],
            "hidden_authors": [
                "channel-13"
            ],
            "user": {
                "user_id": "u-43"
            }
        },
        {
            "attributes": {
                "tier": "silver"
            },
            "personalization": false,
            "user": {
                "user_id": "u-44"
            }
        }
    ]
}

ProfileBatchResponse#

Пример

{
    "results": [
        {
            "index": 0,
            "ok": true
        },
        {
            "error": {
                "code": "validation_failed",
                "details": [
                    {
                        "code": "pii_not_allowed",
                        "field": "attributes.email",
                        "message": "персональные данные не принимаются"
                    }
                ],
                "message": "Поля не прошли проверку"
            },
            "index": 1,
            "ok": false
        }
    ]
}

ProfileBatchResult#

ProfileRequest#

Переданные поля заменяются, null очищает поле, непереданные не меняются.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "age": 29,
    "attributes": {
        "subscriptions": 3,
        "tier": "gold"
    },
    "city": "Казань",
    "followed_authors": [
        "channel-7"
    ],
    "gender": "female",
    "interests": [
        "горные велосипеды",
        "фотография"
    ],
    "user": {
        "user_id": "u-42"
    }
}

ProfileResponse#

Пример

{
    "identity": "user",
    "updated_fields": [
        "gender",
        "birth_year"
    ]
}

RecommendationUser#

Идентификаторы пользователя (ТЗ §8): хотя бы одно поле.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "anonymous_id": "b7f3c9",
    "user_id": "u-42"
}

ReprocessRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "steps": [
        "summary",
        "embedding"
    ]
}

RerankItem#

RerankRequest#

Упорядочить свои id по оценке ленты пользователя.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "items": [
        "v-5",
        "v-9",
        "v-12"
    ],
    "user": {
        "user_id": "u-42"
    }
}

RerankResponse#

Пример

{
    "identity": "user",
    "items": [
        {
            "id": "v-9",
            "score": 0.5521
        },
        {
            "id": "v-5",
            "score": 0.4108
        },
        {
            "id": "v-12"
        }
    ],
    "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W5"
}

SearchChunkOut#

SearchItem#

Найденный объект.

SearchMatch#

Фрагмент объекта, близкий к запросу. Поля без значения не передаются.

Пример

{
    "end_sec": 675.5,
    "media_position": 0,
    "start_sec": 585,
    "text": "…и теперь добавляем свёклу…"
}

SearchRequest#

Поиск: первая страница (offset = 0) ищет заново, следующие берутся из снимка результатов.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "filters": {
        "category": {
            "in": [
                "food"
            ]
        }
    },
    "limit": 20,
    "offset": 0,
    "query": "как приготовить борщ",
    "types": [
        "video",
        "text"
    ],
    "user": {
        "anonymous_id": "b7f3c9",
        "user_id": "u-42"
    }
}

SearchResponse#

Страница результатов поиска.

Пример

{
    "has_more": true,
    "identity": "user",
    "items": [
        {
            "id": "v-123",
            "matches": [
                {
                    "end_sec": 675.5,
                    "media_position": 0,
                    "start_sec": 585,
                    "text": "…и теперь добавляем свёклу…"
                }
            ],
            "score": 1.2841
        },
        {
            "id": "a-7",
            "matches": [],
            "score": 0.9312
        }
    ],
    "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W6"
}

SimilarItem#

SimilarRequest#

Похожие на объект (item) или «дополните заказ» для корзины (items): ровно одно из двух полей.

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "item": "v-123",
    "limit": 8,
    "user": {
        "user_id": "u-42"
    }
}

SimilarResponse#

Пример

{
    "identity": "user",
    "items": [
        {
            "id": "v-88",
            "reason": "similar",
            "score": 0.7311
        }
    ],
    "mode": "cold",
    "recommendation_id": "01J8Z3K4M5N6P7Q8R9S0T1V2W4"
}

StoredProfile#

Пример

{
    "attributes": {
        "tier": "gold"
    },
    "birth_year": 1997,
    "city": "казань",
    "fields_updated_at": {
        "birth_year": "2026-09-14T12:00:00Z",
        "gender": "2026-09-14T12:00:00Z"
    },
    "followed_authors": [
        "channel-7"
    ],
    "gender": "female",
    "identity": "user",
    "interests": [
        "горные велосипеды"
    ],
    "personalization": true
}

SummaryOut#

TranscriptOut#

TranscriptSegment#

UserDeleteRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "user": {
        "user_id": "u-42"
    }
}

UserDeleteResponse#

Пример

{
    "deleted": true
}

UserLinkRequest#

Другие поля не принимаются: неизвестное поле — ошибка unknown_field.

Пример

{
    "anonymous_id": "b7f3c9",
    "fingerprint_uuid": "0b8f6a52-3f3e-4a57-9d51-6c1a1f0e7a01",
    "user_id": "u-42"
}

UserLinkResponse#

Пример

{
    "events_moved": 12,
    "merged": true
}

WebhookItem#

WebhookModeration#

WebhookPayload#

Пример

{
    "delivery_id": "Dl1very0000A",
    "event": "item.processed",
    "item": {
        "id": "v-1042",
        "processing": {
            "embedding": "done",
            "prepare": "done",
            "speech": "done",
            "summary": "done",
            "vision": "done"
        },
        "status": "ready",
        "summary": {
            "age_rating": "0+",
            "moderation": {
                "categories": {
                    "adult": 0,
                    "violence": 0
                },
                "evidence": [],
                "level": "none"
            },
            "summary": "Как выбрать горный велосипед: рама, колёса и тормоза",
            "tags": [
                "велосипед",
                "горный велосипед",
                "тормоза"
            ],
            "topics": [
                "велоспорт",
                "снаряжение"
            ]
        }
    },
    "project_id": "XXXXXXXXXXXX",
    "sent_at": "2026-09-21T14:00:00.000Z"
}

WebhookProcessing#

WebhookSummary#