Publiczne API CommentTap

REST API do kampanii, leadów, analityki, konwersji i publikacji — pod Zapiera, Make'a i własne integracje. Dostępne od planu Business.

Uwierzytelnianie

Utwórz klucz API w Ustawieniach → Klucze API i wysyłaj go jako token Bearer w każdym zapytaniu.

curl https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_your_api_key"

Klucze mają zakresy per zasób i są pokazywane tylko raz przy utworzeniu. Odwołanie klucza natychmiast blokuje jego zapytania.

Zakresy

Każdy klucz niesie jawną listę zakresów. Zapytania poza zakresami klucza zwracają 403 insufficient_scope.

campaigns:readcampaigns:writeleads:readanalytics:readconversions:writepublications:readpublications:write

Endpointy

Wszystkie endpointy żyją pod /v1 i przyjmują/zwracają JSON.

GET/v1/campaignscampaigns:read

Lista kampanii w workspace.

curl https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_..."

POST/v1/campaignscampaigns:write

Utworzenie kampanii. Obowiązują te same walidacje i limity planu, co w aplikacji.

curl -X POST https://api-production-694d.up.railway.app/v1/campaigns \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Lead magnet","type":"comment_to_dm", ...}'

GET/v1/leadsleads:read

Lista zebranych leadów. Paginacja kursorem keyset (limit + cursor).

curl "https://api-production-694d.up.railway.app/v1/leads?limit=50" \
  -H "Authorization: Bearer ct_..."

GET/v1/analytics/funnelanalytics:read

Metryki lejka (komentarze → DM-y → kliknięcia → leady) plus przychód przy włączonym śledzeniu konwersji.

curl "https://api-production-694d.up.railway.app/v1/analytics/funnel?days=30" \
  -H "Authorization: Bearer ct_..."

POST/v1/conversionsconversions:write

Zapis konwersji. Przekaż externalId (np. id zamówienia) dla idempotencji.

curl -X POST https://api-production-694d.up.railway.app/v1/conversions \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"amountCents":4999,"currency":"USD","externalId":"order-1042","email":"customer@example.com"}'

GET/v1/publicationspublications:read

Lista publikacji Instagram utworzonych przez CommentTap.

curl https://api-production-694d.up.railway.app/v1/publications \
  -H "Authorization: Bearer ct_..."

POST/v1/publicationspublications:write

Publikacja lub zaplanowanie posta na Instagramie. Typy mediów i planowanie zgodne z planem.

curl -X POST https://api-production-694d.up.railway.app/v1/publications \
  -H "Authorization: Bearer ct_..." \
  -H "Content-Type: application/json" \
  -d '{"socialAccountId":"...","mediaType":"IMAGE","caption":"New drop 🎉", ...}'

Odpowiedzi i błędy

Odpowiedzi list zwracają { data, nextCursor }; przekaż nextCursor z powrotem jako ?cursor=, aby pobrać kolejną stronę (null = brak kolejnych stron). Pojedyncze obiekty zwracają { data }.

{ "data": [ ... ], "nextCursor": "2026-08-01T10:00:00.000Z|9f1c..." }

Błędy mają stabilny kształt z maszynowym kodem:

{ "error": { "code": "insufficient_scope", "message": "Forbidden" } }

Kod	HTTP	Opis
`unauthorized`	401	Brakujący, błędny, nieznany lub odwołany klucz API.
`insufficient_scope`	403	Klucz nie zawiera zakresu wymaganego przez ten endpoint.
`api_access_requires_upgrade`	402	Plan workspace'u nie obejmuje dostępu do API (Business i wyżej).
`validation_failed`	400	Body lub query nie przeszły walidacji — details wskazuje pola z błędami.
`rate_limited`	429	Za dużo zapytań — zwolnij i ponów po minucie.
`not_found`	404	Zasób nie istnieje w tym workspace.
`internal_error`	500	Nieoczekiwany błąd serwera — można bezpiecznie ponowić z backoffem.

Endpointy bramkowane funkcjami mogą zwracać dodatkowe kody 402/403 wprost z danej bramki, np. conversion_tracking_requires_upgrade lub scheduling_locked — nierozpoznany kod przy tych statusach traktuj jako ograniczenie planu.

Idempotencja

POST /v1/conversions deduplikuje po externalId: wysłanie tego samego externalId dwa razy zwraca { id: null, duplicate: true } zamiast tworzyć drugą konwersję. Użyj id zamówienia lub rezerwacji.

Limity zapytań

Zapytania są limitowane per klucz: 300/min na Business i 1000/min na Scale. Przekroczenie limitu zwraca 429 rate_limited.

Gotowi budować?

Utwórz pierwszy klucz API w aplikacji i wykonaj pierwsze zapytanie w kilka minut.

Otwórz klucze API