API документация

Авторизация

Передайте токен в заголовке Authorization: Bearer sk_live_…. В URL его класть не нужно — токен попадёт в логи серверов и историю браузера.

Токены выпускаются в кабинете после подтверждения email, максимум 5 активных на аккаунт. Полное значение показывается один раз — храните его только на сервере и отзывайте при утечке. Тот же токен, что в кабинете, покрывает скоупы ниже: metadata:read, analyze:write, library:write, ai:write, keywords:write. Токен передавайте только в заголовке Authorization. Анализ на запросе списывает комментарии с баланса (иначе 402 quota_exceeded). CORS: Bearer работает с любого origin без cookie; cookie-сессия — только наши домены и CSRF.

Песочница — без токена

POST /api/v1/sandbox/metadata и POST /api/v1/sandbox/analyze отдают фикстуры той же формы, что боевые эндпоинты: без TikTok, без квоты и без токена. Лимит по IP — 5 запросов в минуту и 30 в час.

# фикстура метаданных (без токена)
curl -X POST https://api.example.com/api/v1/sandbox/metadata \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# фикстура полного анализа (сразу status: complete)
curl -X POST https://api.example.com/api/v1/sandbox/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/metadata — бесплатно

Синхронный ответ: автор, метрики, хештеги, музыка, обложка, ключевые слова описания. Комментариев здесь нет. С токеном или сессией — 10 запросов за 2 часа на аккаунт. С сайта без входа — 10 запросов в сутки (только браузер). Неудачный разбор лимит не расходует. Ответы кэшируются 5 минут по URL, попадание в кэш ("cached": true) лимит не расходует. Curl и свои клиенты — только с Bearer.

curl -X POST https://api.example.com/api/v1/metadata \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/analyze — по балансу комментариев

Асинхронный: возвращает job_id со статусом queued, результат забирается через GET /api/v1/analyze/{job_id}. Опрашивайте раз в 1–2 секунды; статусы — queued, in_progress, complete, failed. Чужая задача отдаёт 404. В comments ответы уже вложены в родительский комментарий как replies. Сохранённый разбор и файлы медиа комментариев живут 14 дней с последнего полного сбора комментариев; открытие закладки срок не продлевает.

# создать задачу
curl -X POST https://api.example.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# ответ: {"job_id": "b1e2...", "status": "queued"}

# забрать результат
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."

Повторы одного URL

Тот же URL не парсится дважды. Если задача ещё выполняется, вернётся её job_id ("deduplicated": "in_flight"). Если результат получен меньше 5 минут назад — вернётся готовая задача ("deduplicated": "recent_result"). В обоих случаях квота не тратится.

Idempotency-Key

Опционально. Если передадите заголовок Idempotency-Key с уникальным значением, повтор с тем же ключом в течение суток вернёт тот же job_id вместо новой задачи. Для обычных запросов заголовок не нужен.

Библиотека и слежение

POST /api/v1/analyses/{ref}/save сохраняет пост. Список — GET /api/v1/analyses/saved, загрузка — GET /api/v1/analyses/{ref}, удаление — DELETE /api/v1/analyses/{ref}. Автообновление — PUT /api/v1/analyses/{ref}/watch, полный пересбор — POST /api/v1/analyses/{ref}/refresh. Последняя сессия браузера — GET /api/v1/analyses/session.

Анализ по токену сам сохраняет пост через bookmark_if_absent: к моменту complete он уже в библиотеке. Опрос GET /api/v1/analyze/{job_id} не продлевает 14-дневный TTL.

От анализа к библиотеке

С токеном готовая задача уже в закладках. Дальше можно включить слежение или ИИ — тот же analysis_id это ref.

# создать задачу
curl -X POST https://api.example.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# забрать результат
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."
# готовая задача — analysis_id уже в библиотеке: {"status":"complete","result":{"analysis_id":"tiktok:7300..."}}

# по желанию: слежение
curl -X PUT https://api.example.com/api/v1/analyses/tiktok:7300.../watch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "interval_min": 60}'

# по желанию: оценка ИИ (затем POST /ai/run)
curl -X POST https://api.example.com/api/v1/ai/quote \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ref": "tiktok:7300..."}'

ИИ

POST /api/v1/ai/quote считает списание, POST /api/v1/ai/run запускает задачу, опрос — GET /api/v1/ai/jobs/{id}. Фразы слежения — PUT /api/v1/ai/{ref}/queries (до трёх). Вызов этих ручек с токеном — согласие отправить тексты комментариев в модель.

Ключевые слова и алерты

GET и PUT /api/v1/keywords — список слов аккаунта. Telegram и HTTPS-колбэки — GET / PUT /api/v1/notification-channels. Совпадения — GET /api/v1/keyword-alerts.

Вебхук задач

Если у webhook-канала включён job_events (по умолчанию выкл), мы отправим POST по завершении задачи: type — job.complete или job.failed, kind — analyze или ai, плюс job_id, ref, url и error. Подпись тела — HMAC в X-Signature, как у алертов по словам.

Эндпоинты

Лимиты и квоты

Ответы содержат X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit, X-Quota-Remaining, а при 429 — Retry-After в секундах. Текущее состояние также отдаёт GET /api/v1/usage.

Когда баланс комментариев исчерпан, анализ отвечает 402 quota_exceeded: купите пакет на странице комментариев — он добавляется к текущему месяцу. Бесплатный лимит на комментарии после регистрации действует только в кабинете: по токену анализ всегда идёт из пакета.

Ошибки

Тело ошибки: {"detail": "...", "code": "machine_code"}