Объекты

Создать или заменить: PUT /items/{id}#

PUT задаёт объект целиком: поля, которых нет в теле, очищаются. Ответ 201 — объект создан, 200 — обновлён. Повтор того же запроса ничего не меняет.

В пути допустимы только символы A-Z a-z 0-9 . _ : -, до 191 символа. Объекты с другими id — кириллицей, пробелами, слешами — передавайте через пакет.

Медиа:

• kind — video, audio или image;
• url — только https и публичный адрес: ссылки на внутренние сети и localhost не принимаются. Видео и аудио читаются по сети без полного скачивания, изображения — до 30 МБ;
• version — необязательная строка до 64 знаков. Заменили файл по той же ссылке — поменяйте version, и медиа обработается заново.

curl -X PUT https://core.daratech.ru/api/v1/items/sku-3107 \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "title": "Куртка утеплённая, графит",
    "author": "brand-north",
    "url": "https://shop.example.ru/p/sku-3107",
    "properties": {"price": 8900, "in_stock": true, "category": "outerwear"},
    "media": [{"kind": "image", "url": "https://cdn.example.ru/sku-3107/1.jpg", "version": "2"}]
  }'

Проверки#

• у text должен быть хотя бы один из title, description, body, а media не передаётся;
• у video должно быть хотя бы одно медиа kind=video, у audio — kind=audio, у image — kind=image; у mixed — любые медиа;
• свойства, которые проект отметил фильтруемыми, должны иметь объявленный тип: строка, число, true/false или список строк;
• неизвестное поле — ошибка: опечатка в имени поля не теряется молча;
• время — ISO-8601 с Z или смещением, время без зоны не принимается;
• пустые строки в author, url и published_at считаются null.

Ошибки полей приходят ответом 422 с полем details:

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

Что переобрабатывается#

Анализ перезапускается только для того, что изменилось:

Свойства попадают в сводку как вспомогательный контекст, но ради них сводка не пересчитывается.

Изменить часть полей: PATCH /items/{id}#

Те же поля, кроме type. Переданные поля заменяются, null очищает поле, остальные не меняются. Правила переобработки — как у PUT. Для несуществующего объекта — 404.

curl -X PATCH https://core.daratech.ru/api/v1/items/sku-3107 \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"available": false, "properties": {"price": 7900, "in_stock": false, "category": "outerwear"}}'

properties заменяются целиком. media: null в PATCH не принимается. PATCH удалённого объекта сохраняет изменения, но удаление не снимает.

Удалить: DELETE /items/{id}#

Мягкое удаление:

• объект исключается из выдачи и поиска;
• результаты анализа и события сохраняются и продолжают участвовать в профилях пользователей;
• повторный DELETE тоже отвечает 200;
• вернуть объект можно только PUT — он снимает удаление.

{"id": "sku-3107", "deleted": true}

Если объект временно нельзя показывать — нет в наличии, снят с публикации, — не удаляйте его, а передайте available: false.

Пакет: POST /items/batch#

До 500 операций put, patch и delete в одном запросе. Операции выполняются по порядку и независимо: ошибка одной не отменяет остальные. В пакете id может содержать любые символы — до 191 символа Unicode.

{"operations": [
  {"op": "put", "id": "статья/2026/09/осень", "data": {"type": "text", "title": "Осенние маршруты", "body": "…"}},
  {"op": "patch", "id": "sku-3107", "data": {"available": true}},
  {"op": "delete", "id": "old-1"}
]}

{"results": [
  {"id": "статья/2026/09/осень", "ok": true, "status": "queued"},
  {"id": "sku-3107", "ok": true, "status": "ready"},
  {"id": "old-1", "ok": false, "error": {"code": "not_found", "message": "Объект не найден"}}
]}

Больше 500 операций — 413 payload_too_large. Ошибки полей в пакете приходят с путями вида data.media[0].url.

Объект и результаты анализа: GET /items/{id}#

Ответ содержит:

• данные объекта: id, type, title, description, author, url, published_at, properties, origin;
• состояние: available, deleted, status, processing, updated_at;
• media: [{position, kind, url, duration_sec, width, height, status}];
• summary: {summary, description, topics, tags, entities, language, age_rating, moderation: {level, categories, evidence}} — когда сводка готова.

Тяжёлые части — по параметру include через запятую:

• transcript — [{media_position, language, timestamps, text, segments: [{start, end, text, speaker}]}]; timestamps — model, если таймкоды дала модель, или estimated, если они оценены;
• frames — [{media_position, ts, duplicate_of_ts, description, tags, ocr_text, safety, image_url}]; image_url — подписанная ссылка, действует час;
• search_chunks — фрагменты поискового индекса.

origin — откуда объект: api, import (загрузка файла в кабинете) или order (товар из заказа, которого не было в каталоге).

Субтитры медиа — GET /items/{id}/subtitles?media=0&format=vtt или format=srt: реплики не длиннее 7 секунд, до 2 строк по 42 знака. Нет транскрипта — 404.

Статус объекта#

Состояние шагов#

В processing — состояние шагов prepare, speech, vision, summary, embedding:

Переобработать: POST /items/{id}/reprocess#

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

Шаги — speech, vision, summary, embedding; зависимые шаги пересчитываются следом. Без steps переобрабатывается всё, включая подготовку медиа. Ответ 202 — как у PUT.

Сверка каталога: GET /items#

Список объектов проекта, включая удалённые, по возрастанию updated_at.

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

next_cursor: null — страниц больше нет. Объект, изменённый во время обхода, встретится на следующих страницах ещё раз. Удобная схема — раз в сутки забирать изменения с updated_since и сравнивать с каталогом у себя.