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

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

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

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

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

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

Каждый ответ содержит заголовок 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, подробности — в разделе Объекты.

Шаг 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.91, "reason": "interest"},
           {"id": "v-1877", "score": 0.84, "reason": "together"},
           {"id": "v-2301", "score": 0.62, "reason": "fresh"}],
 "has_more": true, "mode": "personal", "identity": "user"}

reason объясняет, почему объект в ленте: по интересам пользователя, «вместе» с тем, что он уже смотрел, свежее. Следующая страница — тот же запрос с offset и полученным recommendation_id. В событиях показа и открытия передавайте recommendation_id, surface и position — по ним считаются метрики выдачи.

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

<?php
function dara(string $method, string $path, array $body): 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_CONNECTTIMEOUT => 3,
        CURLOPT_TIMEOUT => 10,
    ]);
    $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']],
]]);

$feed = dara('POST', '/recommendations/feed', ['user' => ['user_id' => 'u-501'], 'limit' => 24]);
foreach ($feed['items'] as $item) {
    echo $item['id'], ' — ', $item['reason'], "\n";
}

Те же запросы на 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,
)

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()

feed = api.post("/recommendations/feed", json={"user": {"user_id": "u-501"}, "limit": 24})
feed.raise_for_status()
for item in feed.json()["items"]:
    print(item["id"], "—", item["reason"])

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

• Каталог. Отправляйте PUT при создании и изменении объекта у себя. Первую загрузку каталога ведите пакетами POST /items/batch по 500 операций.
• События. Копите события в очереди на сервере и отправляйте пачками раз в несколько секунд. При сетевой ошибке, 429 или 5xx повторяйте ту же пачку: дубли по id не учитываются.
• Вход. Когда посетитель входит или регистрируется, вызовите POST /users/link — история анонима перейдёт в аккаунт.
• Выдача. Запрашивайте ленту с таймаутом около двух секунд и держите запасной вариант — например, хронологическую ленту.

Что дальше#

• Понятия — проект, объект, типы событий, пользователи, снимки выдачи.
• Объекты — поля, проверки, статусы анализа, удаление.
• События и заказы — пресеты, режимы учёта, заказы и отмены.
• Пользователи и Данные о пользователях — идентификаторы, склейка при входе, профиль.
• Справочник API — методы и схемы.