Pierwsze kroki

REST API Senuto pozwala pobierać dane z modułów Senuto (Analiza widoczności, Monitoring, Baza słów kluczowych i inne) bezpośrednio do Twoich integracji. Bazowy adres:


https://api.senuto.com

Twoje pierwsze zapytanie

Od zera do pierwszej odpowiedzi: pobierzemy token, a nim — frazy, na które rankuje domena (positions/getData z Analizy Widoczności).

Pobierz token

Potrzebujesz konta Senuto z aktywnym dostępem do API. Token JWT (ważny 31 dni) pobierzesz e‑mailem i hasłem konta:


curl --location --request POST 'https://api.senuto.com/api/users/token' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "email": "twoj@email.com", "password": "TWOJE_HASŁO" }'

Token znajdziesz w polu data.token odpowiedzi. Wolisz bez terminala? Zaloguj się tutaj — token zostanie też zapamiętany w playgroundzie:

Pobierz token tutaj

Zaloguj się danymi konta Senuto — token trafi do pola poniżej i do playgroundu na stronach endpointów. Hasło jest wysyłane wyłącznie do api.senuto.com i nigdzie nie jest zapisywane. Konto musi mieć aktywny dodatek API.

Szczegóły przepływu — formaty ciała, pełna odpowiedź, błędy autoryzacji, zasady bezpieczeństwa — są na stronie Autoryzacja.

Wyślij żądanie

Wstaw token w miejsce $YOUR_TOKEN_HERE w przykładzie poniżej — albo kliknij Wypróbuj ten endpoint i wyślij żądanie z przeglądarki, bez pisania kodu:

POST/api/visibility_analysis/reports/positions/getData

Wymagane pola tego raportu to domain i fetch_mode:

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/reports/positions/getData' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "domain": "zalando.pl", "fetch_mode": "topLevelDomain" }'

Odczytaj odpowiedź

Odpowiedź jest opakowana w success / data / pagination:

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    { "keyword_id": 184, "keyword": "toni and paul", "statistics": { "position": { "current": 29 } /* … */ } }
  ],
  "pagination": { "page_count": 97041, "current_page": 1, "has_next_page": true, "count": 291121, "limit": 10 }
}

Zasady ogólne

Adres endpointu ma postać /api/<moduł>/<sekcja>/<kontroler>/<akcja>, na przykład /api/visibility_analysis/reports/positions/getData.

Moduł, sekcję i kontroler zapisujesz w snake_case (ai_overviews, domains_ranking), ale akcję zawsze w camelCase (getData, getDomainStatistics). Zapisana jako get_data zwróci 404. Pozostałe przyczyny 404: Błędy.

Nagłówki. Każde żądanie wymaga Authorization: Bearer <token>; przy POST dodaj też Content-Type: application/json.
fetch_mode (wymagane w wielu endpointach) określa, jak interpretowana jest domain. Dozwolone wartości: topLevelDomain (cała domena — to jest „domain”), subdomain, catalog, url.
Koperta odpowiedzi. Sukces: { "success": true, "data": …, "pagination": … }. Błąd: { "success": false, "data": { "error": { "type", "message", "params" } } }.
GET vs POST. Większość raportów to POST z ciałem JSON, ale część (np. Dashboard) to GET z parametrami w query stringu — wysłanie ich w ciele JSON zwraca wtedy 418. Metoda jest podana na stronie każdego endpointu.
Paginacja. Tam gdzie zwracana jest lista, używaj limit (domyślnie 10) i page (domyślnie 1); meta jest w pagination.

Status 418 oznacza błąd walidacji żądania (invalid_data) — nie tylko przekroczenie limitu zapytań. W polu data.error.params znajdziesz, które pole jest nieprawidłowe, np. brak wymaganego fetch_mode.

Co dalej

Autoryzacja — pozyskanie i odświeżanie tokenu, wymagany dostęp do API, błędy autoryzacji.
Moduły — endpointy raportowe (Analiza widoczności, Monitoring, Baza słów kluczowych…) z interaktywnym playgroundem.
Typy — wspólne struktury: Filter (parametr filtering), Paginacja (limit/page), Błędy (koperta błędu i status 418).