---
title: "Pierwsze kroki"
source: https://docs.senuto.com/get-started
---

# 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:

```bash
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:

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

### 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**

```bash
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" }'
```

**JSON (body)**

```json filename="ciało żądania"
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}
```

### Odczytaj odpowiedź

Odpowiedź jest opakowana w `success` / `data` / `pagination`:

```json filename="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`.

> **Ostrzeżenie:**
> 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](/types/errors).

- **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`.

> **Błąd:**
> 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](/authorization)** — pozyskanie i odświeżanie tokenu, wymagany dostęp do API, błędy autoryzacji.
- **[Moduły](/modules)** — endpointy raportowe (Analiza widoczności, Monitoring, Baza słów kluczowych…) z interaktywnym playgroundem.
- **[Typy](/types)** — wspólne struktury: [`Filter`](/types/filter) (parametr `filtering`), [Paginacja](/types/pagination) (`limit`/`page`), [Błędy](/types/errors) (koperta błędu i status `418`).