ДАРА
Кабинет Оставить заявку
Разделы документации

ДокументацияНачало

Быстрый старт

Как получить доступ к API ДАРА и отправить первые три запроса — объект, события и ленту — на curl, PHP и Python.

ДАРА принимает по API ваш контент и действия посетителей, анализирует контент и возвращает персональную выдачу. API работает только сервер-сервер: ключ проекта хранится на вашем сервере и в браузер не попадает.

Как получить доступ

  1. Заявка. Оставьте заявку на подключение: имя, email, тип контента и размер каталога. Мы ответим на указанный адрес, обсудим задачу и стоимость. Саморегистрации и онлайн-оплаты нет.
  2. Кабинет. После подключения на ваш email придёт приглашение. В кабинет входят по одноразовому коду из письма, паролей нет.
  3. Проект и ключ. Создайте в кабинете проект и выберите пресет — «Видеохостинг», «Магазин», «Медиа» или «Свой»: от него зависят типы событий. На вкладке «Ключи API» создайте ключ. Полный ключ показывается один раз — сохраните его в секретах сервера. Потерянный ключ отзовите и выпустите новый: отзыв действует сразу.

Ключ проекта — ck_ и 40 латинских букв и цифр. В примерах вместо него заглушка ck_XXXXXXXX….

Основы запросов

Что Как
Адрес API https://core.daratech.ru/api/v1
Ключ заголовок Authorization: Bearer ck_XXXXXXXX…; в адресе и параметрах ключ не принимается
Формат JSON в UTF-8, заголовок Content-Type: application/json
Время ISO-8601 с зоной: 2026-09-14T12:00:00Z
Ошибки {"error": {"code", "message", "details"}} — см. Ошибки и лимиты

Каждый ответ содержит заголовок X-Request-ID. Пишите его в свои логи: по нему мы найдём запрос, если понадобится разбор.

Шаг 1. Передайте объект

Объект — единица контента: видео, изображение, аудио, текст или товар. В адресе — ваш id объекта. Повторный PUT с тем же id заменяет объект, поэтому запрос можно безопасно повторять.

export DARA_KEY='ck_XXXXXXXX…'

curl -X PUT https://core.daratech.ru/api/v1/items/v-1042 \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "title": "Как выбрать горный велосипед",
    "description": "Сравниваем рамы, вилки и тормоза",
    "author": "channel-17",
    "url": "https://example.ru/video/v-1042",
    "published_at": "2026-09-14T09:00:00Z",
    "media": [{"kind": "video", "url": "https://cdn.example.ru/v-1042.mp4"}]
  }'

Ответ 201 Created — объект создан и поставлен в очередь анализа:

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

Анализ идёт в фоне. Состояние объекта и результаты — GET /items/v-1042, подробности — в разделе Объекты. Чтобы не опрашивать ДАРА, подпишитесь на вебхук item.processed.

Шаг 2. Отправьте события

Событие — действие посетителя с объектом: показ, открытие, досмотр, лайк, покупка. Коды типов задаёт пресет проекта, список — GET /event-types. Пользователь передаётся объектом user: user_id — id аккаунта на вашем сайте, anonymous_id — id браузера или устройства, который выдаёт ваш сайт.

curl -X POST https://core.daratech.ru/api/v1/events \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"id": "evt-88121", "type": "view", "item": "v-1042",
       "user": {"user_id": "u-501"}, "occurred_at": "2026-09-14T12:00:00Z",
       "recommendation_id": "01JC8Z6Q9W3M5N7P2R4T6V8X0Y", "surface": "feed", "position": 3},
      {"id": "evt-88122", "type": "watch", "item": "v-1042",
       "user": {"user_id": "u-501"}, "value": 540}
    ]
  }'

Ответ 202 Accepted:

{"accepted": 2, "duplicates": 0, "rejected": []}

id события уникален в проекте: повторно присланное событие не учитывается второй раз. Отправляйте события пачками до 1000 штук.

Шаг 3. Запросите ленту

curl -X POST https://core.daratech.ru/api/v1/recommendations/feed \
  -H "Authorization: Bearer $DARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": {"user_id": "u-501"}, "limit": 24}'

{"recommendation_id": "01JC8Z6Q9W3M5N7P2R4T6V8X0Y",
 "items": [{"id": "v-2210", "score": 0.9132, "reason": "interest"},
           {"id": "v-1877", "score": 0.8417, "reason": "together"},
           {"id": "v-2301", "score": 0.6205, "reason": "fresh"}],
 "has_more": true, "mode": "personal", "identity": "user"}
  • reason объясняет, почему объект в ленте: по интересам пользователя, «вместе» с тем, что он уже смотрел, новое.
  • mode — режим: personal — по профилю пользователя, cold — для нового посетителя, fallback — запасная выдача; identity — как определён пользователь.
  • Следующая страница — тот же запрос с offset, например "offset": 24: она продолжает ту же выдачу без повторов, recommendation_id передавать не обязательно.
  • В событиях показа и открытия передавайте recommendation_id, surface и position (с 0) — по ним считаются метрики выдачи.

Похожие, «дополните заказ», переранжирование, фильтры и метрики — в разделе Рекомендации.

Те же запросы на PHP

<?php
// Запись каталога и событий ждёт ответа до 10 с, выдача — около 700 мс (см. «Рекомендации»).
function dara(string $method, string $path, array $body, int $timeoutMs = 10000, int $connectMs = 3000): array
{
    $ch = curl_init('https://core.daratech.ru/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('DARA_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_NOSIGNAL => true,
        CURLOPT_CONNECTTIMEOUT_MS => $connectMs,
        CURLOPT_TIMEOUT_MS => $timeoutMs,
    ]);
    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($response === false || $status >= 400) {
        throw new RuntimeException('ДАРА: HTTP ' . $status . ' ' . ($response ?: curl_error($ch)));
    }
    return json_decode($response, true);
}

dara('PUT', '/items/v-1042', [
    'type' => 'video',
    'title' => 'Как выбрать горный велосипед',
    'author' => 'channel-17',
    'media' => [['kind' => 'video', 'url' => 'https://cdn.example.ru/v-1042.mp4']],
]);

dara('POST', '/events', ['events' => [
    ['id' => 'evt-88121', 'type' => 'view', 'item' => 'v-1042', 'user' => ['user_id' => 'u-501']],
]]);

try {
    $feed = dara('POST', '/recommendations/feed', ['user' => ['user_id' => 'u-501'], 'limit' => 24], 700, 200);
    foreach ($feed['items'] as $item) {
        echo $item['id'], ' — ', $item['reason'], "\n";
    }
} catch (Throwable $e) {
    // таймаут или ошибка — покажите свою ленту, например хронологическую
}

Те же запросы на Python

import os

import httpx

api = httpx.Client(
    base_url="https://core.daratech.ru/api/v1",
    headers={"Authorization": f"Bearer {os.environ['DARA_KEY']}"},
    timeout=10,  # запись каталога и событий; у выдачи тайм-аут свой, около 700 мс
)

api.put("/items/v-1042", json={
    "type": "video",
    "title": "Как выбрать горный велосипед",
    "author": "channel-17",
    "media": [{"kind": "video", "url": "https://cdn.example.ru/v-1042.mp4"}],
}).raise_for_status()

api.post("/events", json={"events": [
    {"id": "evt-88121", "type": "view", "item": "v-1042", "user": {"user_id": "u-501"}},
]}).raise_for_status()

try:
    feed = api.post("/recommendations/feed", json={"user": {"user_id": "u-501"}, "limit": 24},
                    timeout=httpx.Timeout(0.7, connect=0.2))
    feed.raise_for_status()
    for item in feed.json()["items"]:
        print(item["id"], "—", item["reason"])
except (httpx.HTTPError, ValueError):
    pass  # таймаут или ошибка — покажите свою ленту, например хронологическую

Как встроить в свой сайт

  • Каталог. Отправляйте PUT при создании и изменении объекта у себя. Первую загрузку каталога ведите пакетами POST /items/batch по 500 операций — или загрузите файлом в кабинете, см. Импорт файлов.
  • События. Копите события в очереди на сервере и отправляйте пачками раз в несколько секунд. При сетевой ошибке, 429 или 5xx повторяйте ту же пачку: дубли по id не учитываются.
  • Вход. Когда посетитель входит или регистрируется, вызовите POST /users/link — история анонима перейдёт в аккаунт.
  • Выдача. Запрашивайте ленту с таймаутом около 700 мс и держите запасной вариант — например, хронологическую ленту: его показывайте при ошибке или таймауте. Если ДАРА не успевает подобрать выдачу, она сама отвечает запасной (mode: fallback).
  • Готовность анализа. Вместо опроса GET /items/{id} подпишитесь на вебхук item.processed — Вебхуки.
  • Поиск. POST /search ищет по смыслу и возвращает фрагменты со временем в видео — Поиск.

Что дальше