Dla programistów

API

Trzy punkty końcowe JSON: skracanie, sprawdzanie slugu i zgłoszenia. Do tego kod QR i strona statystyk. Bez kluczy i bez rejestracji.

Skracanie adresu

POST https://skracarka.com/api/shorten

Treść żądania jako JSON (Content-Type: application/json) albo zwykły formularz (application/x-www-form-urlencoded).

Pole	Wymagane	Opis
`url`	tak	Adres do skrócenia. Bez schematu dopisujemy `https://`. Tylko http i https, do 2048 bajtów po zakodowaniu procentowym (znak spoza ASCII zajmuje kilka bajtów).
`slug`	nie	Własna końcówka: 3–32 znaki, litery, cyfry, `-` i `_` (nie na początku ani końcu). Wielkość liter nie ma znaczenia przy sprawdzaniu zajętości.
`expires`	nie	Termin ważności w dniach: `7`, `30` albo `365`. Pusty = bezterminowo.

Przykład

curl -X POST https://skracarka.com/api/shorten \
  -H "Content-Type: application/json" \
  -d '{
        "url":  "https://example.com/bardzo/dlugi/adres",
        "slug": "wrzesien",
        "expires": "30"
      }'

Odpowiedź 201 Created

{
  "ok": true,
  "slug": "wrzesien",
  "short_url": "https://skracarka.com/wrzesien",
  "target": "https://example.com/bardzo/dlugi/adres",
  "stats_url": "https://skracarka.com/wrzesien+",
  "qr_url": "https://skracarka.com/qr/wrzesien.svg",
  "created_at": "2026-09-06T10:15:00Z",
  "expires_at": "2026-10-06T10:15:00Z",
  "existing": false
}

Gdy ten sam adres był już skrócony bez własnego slugu i bez terminu, dostaniesz istniejący link ze statusem 200 i polem "existing": true.

Błędy

{
  "ok": false,
  "error": "Ten slug jest już zajęty — wybierz inny.",
  "field": "slug",
  "code": "slug_taken"
}

Pole field wskazuje pole z błędem (url, slug, expires). Przy błędach ogólnych ma wartość null albo go nie ma.

Status	`code`	Znaczenie
422	`empty`	Puste pole `url`.
422	`invalid`	Adres nie daje się przetworzyć albo przysłano wartość, która nie jest tekstem.
422	`scheme`	Schemat inny niż http i https.
422	`host`	Zła nazwa domeny albo adres niepubliczny (pętla zwrotna, sieć prywatna, zapis liczbowy).
422	`port`	Po dwukropku nie ma poprawnego numeru portu.
422	`userinfo`	Adres zawiera dane logowania (`login:hasło@host`).
422	`idn`	Domena ze znakami spoza ASCII, a serwer nie ma rozszerzenia `intl`.
422	`self`	Adres prowadzi do tej skracarki — to byłaby pętla.
422	`too_long`	Adres dłuższy niż 2048 bajtów.
422	`slug_invalid`, `slug_taken`	Problem z własnym slugiem.
422	`expires_invalid`	Nieznana wartość `expires`.
422	`collision`	Nie udało się wylosować wolnego adresu — powtórz żądanie.
400	`spam`	Wypełnione pole-pułapka.
403	`origin`	Zgłoszenie nadużycia wysłane z obcej strony.
404	`not_found`	Nieznany punkt końcowy.
422	`not_found`	Nieznany slug w zgłoszeniu nadużycia.
422	`reason`	Brak albo nieznany powód zgłoszenia.
405	`method`	Zła metoda — użyj POST.
429	`rate_limited`	Za dużo żądań — czas oczekiwania w sekundach podaje nagłówek `Retry-After`.
500	`server`	Błąd po naszej stronie.
503	`unavailable`	Baza chwilowo nie odpowiada — ponów za kilkadziesiąt sekund.

Sprawdzanie slugu

GET https://skracarka.com/api/check?slug=wrzesien

{
  "ok": true,
  "slug": "wrzesien",
  "available": false,
  "code": "taken",
  "label": "zajęty",
  "reason": "Ten slug jest już zajęty."
}

Pole available mówi, czy slug jest wolny. Przy odmowie code podaje powód w formie nadającej się do porównania w kodzie, label to krótka etykieta do pokazania przy polu, a reason — pełne zdanie dla użytkownika.

`code`	Znaczenie
`taken`	Slug jest już zajęty.
`reserved`	Slug zarezerwowany przez serwis.
`syntax`	Niedozwolone znaki albo myślnik na początku lub końcu.
`too_short`, `too_long`	Poza zakresem 3–32 znaków.
`null`	Slug jest wolny (`available: true`).

Kod QR

GET https://skracarka.com/qr/{slug}.svg — kod QR krótkiego linku jako SVG (skalowalny, nadaje się do druku).

Statystyki

GET https://skracarka.com/{slug}+ — strona HTML z podglądem celu, liczbą kliknięć i kodem QR. Dopisz plus do krótkiego linku w przeglądarce, aby sprawdzić cel bez przekierowania.

Zgłoszenie nadużycia

POST https://skracarka.com/api/report

Pola: slug (wymagany), powod (phishing, malware, spam, oszustwo, inne) oraz opis (opcjonalny, do 500 znaków).

Odpowiedź jest JSON-em, gdy wyślesz Content-Type: application/json albo Accept: application/json — wtedy 202 i {"ok": true}. Zwykły formularz (bez tych nagłówków) dostaje przekierowanie 303 z powrotem na stronę statystyk z komunikatem. Zgłoszenia przyjmujemy tylko z tej witryny: żądanie z nagłówkiem Origin wskazującym inną domenę dostaje 403 i code: "origin".

Limity i zasady

do 30 nowych linków na 10 minut z jednego adresu (dla IPv6 liczymy prefiks /64);
osobne liczniki na minutę: 60 wywołań /api/shorten, 180 wywołań /api/check, 10 wywołań /api/report oraz 30 wysłań formularza na stronie głównej;
CORS włączony — API można wywołać bezpośrednio z przeglądarki;
obowiązuje regulamin: żadnych linków do phishingu, złośliwego oprogramowania i spamu.