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"}