Dokumentacja API

Wprowadzenie

API rdir pozwala na programatyczne tworzenie, zarządzanie i śledzenie skróconych linków. Wszystkie endpointy API używają JSON dla zapytań i odpowiedzi.

Bazowy URL dla endpointów

https://rdir.pl/api/v1

Uwierzytelnianie

Wszystkie zapytania API muszą zawierać poprawny token API w nagłówku Authorization używając schematu Bearer.

Przykładowe zapytanie

curl https://rdir.pl/api/v1/links \
  -H "Authorization: Bearer rdir_TWÓJ_TOKEN"

Uwaga

Nigdy nie udostępniaj swoich tokenów API w kodzie po stronie klienta lub publicznych repozytoriach.
Przechowuj je bezpiecznie używając zmiennych środowiskowych.

Limity zapytań

Zapytania API są limitowane per token. Domyślny limit to 100 zapytań na godzinę.

Informacje o limitach są zawarte w nagłówkach odpowiedzi każdego zapytania:

Nagłówki odpowiedzi

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1706875200

X-RateLimit-Limit — Maksymalna liczba zapytań dozwolona na godzinę

X-RateLimit-Remaining — Pozostała liczba zapytań w bieżącym oknie

X-RateLimit-Reset — Znacznik czasu Unix kiedy limit zostanie zresetowany

Jeśli przekroczysz limit zapytań, API zwróci odpowiedź 429 Too Many Requests.

Błędy

API używa standardowych kodów statusu HTTP i zwraca błędy w spójnym formacie JSON:

Odpowiedź błędu

{
  "error": {
    "type": "validation_error",
    "message": "Walidacja zapytania nie powiodła się",
    "details": {
      "url": "URL musi zaczynać się od http:// lub https://"
    }
  },
  "status": 422
}

Kody statusu

401Unauthorized — Brak lub nieprawidłowy token API

403Forbidden — Token został unieważniony lub brak uprawnień

404Not Found — Zasób nie istnieje

422Unprocessable Entity — Błąd walidacji

429Too Many Requests — Przekroczono limit zapytań

500Internal Server Error — Coś poszło nie tak

Endpointy

Utwórz link

Utwórz nowy skrócony link. Wymagany jest tylko docelowy URL.

POSThttps://rdir.pl/api/v1/links

Treść zapytania

urlstringrequired

Docelowy URL do skrócenia. Musi zaczynać się od http:// lub https://

shortCodestring

Własny skrót (3-50 znaków). Jeśli nie podano, zostanie wygenerowany automatycznie.

titlestring

Tytuł linku do celów wyświetlania

tagsstring[]

Tablica nazw tagów do organizacji linków

referrerstring

Parametr ref do śledzenia źródła odsyłacza

utmSourcestring

Parametr UTM source do śledzenia

utmMediumstring

Parametr UTM medium

utmCampaignstring

Parametr UTM campaign

utmTermstring

Parametr UTM term (słowa kluczowe)

utmContentstring

Parametr UTM content (wariant reklamy)

iosUrlstring

URL specyficzny dla iOS do deep linkingu

androidUrlstring

URL specyficzny dla Android do deep linkingu

Przykładowe zapytanie

curl -X POST https://rdir.pl/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very-long-url",
    "shortCode": "example",
    "title": "Example Page",
    "tags": ["marketing", "social"]
  }'

Odpowiedź (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortCode": "example",
  "shortUrl": "https://rdir.pl/example",
  "url": "https://example.com/very-long-url",
  "title": "Example Page",
  "qrCodeUrl": "https://rdir.pl/api/qr/example",
  "tags": ["marketing", "social"],
  "createdAt": "2026-02-02T10:30:00Z",
  "updatedAt": "2026-02-02T10:30:00Z"
}

Lista linków

Pobierz stronicowaną listę wszystkich linków w Twoim workspace.

GEThttps://rdir.pl/api/v1/links

Parametry zapytania

pagenumberdefault: 1

Numer strony dla paginacji

limitnumberdefault: 50

Liczba elementów na stronę (max: 100)

searchstring

Szukaj po tytule, opisie lub skrócie

tagstring

Filtruj po nazwie tagu

sortBystringdefault: createdAt

Pole sortowania: createdAt, updatedAt

sortOrderstringdefault: desc

Kolejność sortowania: asc, desc

Przykładowe zapytanie

curl "https://rdir.pl/api/v1/links?page=1&limit=20&search=example" \
  -H "Authorization: Bearer YOUR_TOKEN"

Odpowiedź (200 OK)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "shortCode": "example",
      "shortUrl": "https://rdir.pl/example",
      "url": "https://example.com",
      "title": "Example Page",
      "tags": ["marketing"],
      "createdAt": "2026-02-02T10:30:00Z",
      "updatedAt": "2026-02-02T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 234,
    "totalPages": 5
  }
}

Pobierz link

Pobierz szczegóły konkretnego linku po jego skrócie.

GEThttps://rdir.pl/api/v1/links/:shortcode

Parametry ścieżki

shortcodestringrequired

Skrót linku do pobrania

Przykładowe zapytanie

curl https://rdir.pl/api/v1/links/example \
  -H "Authorization: Bearer YOUR_TOKEN"

Odpowiedź (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortCode": "example",
  "shortUrl": "https://rdir.pl/example",
  "url": "https://example.com/very-long-url",
  "title": "Example Page",
  "clickCount": 142,
  "tags": ["marketing", "social"],
  "createdAt": "2026-02-02T10:30:00Z",
  "updatedAt": "2026-02-02T10:30:00Z"
}

Zaktualizuj link

Zaktualizuj istniejący link. Wszystkie pola są opcjonalne - zaktualizowane zostaną tylko podane pola.

PATCHhttps://rdir.pl/api/v1/links/:shortcode

Parametry ścieżki

shortcodestringrequired

Skrót linku do zaktualizowania

Treść zapytania

urlstring

Zaktualizuj docelowy URL

titlestring

Zaktualizuj tytuł linku

tagsstring[]

Zamień tagi linku

Przykładowe zapytanie

curl -X PATCH https://rdir.pl/api/v1/links/example \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "tags": ["updated", "marketing"]
  }'

Odpowiedź (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortCode": "example",
  "shortUrl": "https://rdir.pl/example",
  "url": "https://example.com/very-long-url",
  "title": "Updated Title",
  "tags": ["updated", "marketing"],
  "updatedAt": "2026-02-02T11:45:00Z"
}

Usuń link

Trwale usuń link. Ta akcja nie może zostać cofnięta.

DELETEhttps://rdir.pl/api/v1/links/:shortcode

Parametry ścieżki

shortcodestringrequired

Skrót linku do usunięcia

Przykładowe zapytanie

curl -X DELETE https://rdir.pl/api/v1/links/example \
  -H "Authorization: Bearer YOUR_TOKEN"

Odpowiedź (204 No Content)

Brak treści odpowiedzi. Status 204 oznacza pomyślne usunięcie.

Potrzebujesz pomocy?

Jeśli masz pytania lub napotkasz problemy z API, skontaktuj się ze mną.