Dokumentacja API

Autoryzacja

Przekaż token w nagłówku Authorization: Bearer sk_live_…. Nie umieszczaj go w URL — trafi wtedy do logów serwerów i historii przeglądarki.

Tokeny tworzysz w panelu po potwierdzeniu e-maila, maksymalnie 5 aktywnych na konto. Pełną wartość pokazujemy raz — trzymaj ją tylko na serwerze i odwołaj przy wycieku. Ten sam token co w panelu pokrywa zakresy poniżej: metadata:read, analyze:write, library:write, ai:write, keywords:write. Token wysyłaj tylko w nagłówku Authorization. Analiza pobiera komentarze z salda (inaczej 402 quota_exceeded). CORS: Bearer działa z dowolnego origin bez ciasteczek; sesja cookie tylko na naszych domenach i z CSRF.

Piaskownica — bez tokena

POST /api/v1/sandbox/metadata i POST /api/v1/sandbox/analyze zwracają dane testowe w tej samej formie co produkcyjne punkty końcowe: bez TikToka, bez limitu i bez tokena. Limit na IP to 5 zapytań na minutę i 30 na godzinę.

# fixture metadanych (bez tokena)
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"}'

# fixture pełnej analizy (od razu 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 — za darmo

Odpowiedź synchroniczna: autor, statystyki, hashtagi, dźwięk, okładka i słowa kluczowe opisu. Komentarzy tu nie ma. Z tokenem lub sesją: 10 zapytań na 2 godziny na konto. Ze strony bez logowania: 10 zapytań na dobę (tylko przeglądarka). Nieudane pobranie nie zużywa limitu. Odpowiedzi są buforowane 5 minut po URL, trafienie w cache ("cached": true) nie zużywa limitu. Curl i własne klienty — tylko z 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 — z salda komentarzy

Asynchronicznie: zwraca job_id ze statusem queued, a wynik pobierasz przez GET /api/v1/analyze/{job_id}. Odpytuj co 1–2 sekundy; statusy to queued, in_progress, complete i failed. Cudze zadanie zwraca 404. W comments odpowiedzi są już zagnieżdżone w komentarzu nadrzędnym jako replies. Zapisana analiza i pliki mediów komentarzy żyją 14 dni od ostatniego pełnego zbioru komentarzy; otwarcie zakładki nie przedłuża terminu.

# utwórz zadanie
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"}'

# odpowiedź: {"job_id": "b1e2...", "status": "queued"}

# pobierz wynik
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."

Powtórzenie tego samego URL

Ten sam URL nie jest parsowany dwa razy. Jeśli zadanie wciąż trwa, dostaniesz jego job_id ("deduplicated": "in_flight"). Jeśli wynik pojawił się mniej niż 5 minut temu, wrócimy z gotowym zadaniem ("deduplicated": "recent_result"). W obu przypadkach limit nie jest zużywany.

Idempotency-Key

Opcjonalnie. Jeśli wyślesz nagłówek Idempotency-Key z unikalną wartością, powtórka z tym samym kluczem w ciągu doby zwróci to samo job_id zamiast nowego zadania. Zwykłe zapytania nie potrzebują tego nagłówka.

Biblioteka i śledzenie

POST /api/v1/analyses/{ref}/save zapisuje post. Lista: GET /api/v1/analyses/saved, odczyt: GET /api/v1/analyses/{ref}, usunięcie: DELETE /api/v1/analyses/{ref}. Auto-odświeżanie: PUT /api/v1/analyses/{ref}/watch, pełny zbiór: POST /api/v1/analyses/{ref}/refresh. Ostatnia sesja przeglądarki: GET /api/v1/analyses/session.

Analiza tokenem sama zapisuje post przez bookmark_if_absent: przy complete jest już w bibliotece. Odpytywanie GET /api/v1/analyze/{job_id} nie przedłuża 14-dniowego TTL.

Od analizy do biblioteki

Z tokenem gotowe zadanie jest już w zakładkach. Potem możesz włączyć śledzenie albo AI — to samo analysis_id to ref.

# utwórz zadanie
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"}'

# pobierz wynik
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."
# gotowe zadanie — analysis_id jest już w bibliotece: {"status":"complete","result":{"analysis_id":"tiktok:7300..."}}

# opcjonalnie: auto-odświeżanie
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}'

# opcjonalnie: wycena AI (potem 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..."}'

AI

POST /api/v1/ai/quote zwraca koszt, POST /api/v1/ai/run startuje zadanie, odpytuj GET /api/v1/ai/jobs/{id}. Frazy śledzenia: PUT /api/v1/ai/{ref}/queries (do trzech). Wywołanie tych ścieżek z tokenem to zgoda na wysłanie tekstów komentarzy do modelu.

Słowa kluczowe i alerty

GET i PUT /api/v1/keywords zarządzają listą słów konta. Telegram i callbacki HTTPS: GET / PUT /api/v1/notification-channels. Trafienia: GET /api/v1/keyword-alerts.

Webhook zadań

Jeśli job_events jest włączone na kanale webhook (domyślnie wyłączone), wyślemy POST po zakończeniu zadania: type to job.complete albo job.failed, kind to analyze albo ai, plus job_id, ref, url i error. Podpis ciała HMAC w X-Signature jak przy alertach słów.

Endpointy

Limity i przydziały

Odpowiedzi zawierają X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit i X-Quota-Remaining, a przy 429 dodatkowo Retry-After w sekundach. Bieżący stan zwraca też GET /api/v1/usage.

Gdy saldo komentarzy się skończy, analiza odpowiada 402 quota_exceeded: kup pakiet na stronie komentarzy, dopiszemy go do bieżącego miesiąca. Darmowy limit na komentarze po rejestracji działa tylko w panelu: z tokenem analiza zawsze idzie z pakietu.

Błędy

Treść błędu: {"detail": "...", "code": "machine_code"}