API

Vytvářejte a spravujte krátké odkazy ze skriptů a aplikací. API je zdarma. Vytvořte si klíč ve své nástěnce v sekci API klíče a posílejte ho jako bearer token.

Ověřování

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Klíče se zobrazí jen jednou. Zacházejte s nimi jako s hesly: kdokoli s vaším klíčem může vytvářet a upravovat odkazy ve vašem účtu. Uniklý klíč zrušte v nástěnce.

Limity

• 60 požadavků za minutu na klíč.
• 500 nových odkazů denně na účet.
• Cíle kontrolujeme proti službě Google Safe Browsing a proti našemu seznamu blokovaných domén. Jiné zkracovače odkazů nelze použít jako cíl.

Vytvoření odkazu

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code je nepovinný (4–32 písmen, číslic, - nebo _). Vynechte ho a získáte náhodný sedmiznakový kód. Odpověď 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

Výpis odkazů

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

Od nejnovějších. Předejte nextCursor z předchozí stránky a získáte další. clicks=1 přidá celkové počty lidských kliknutí.

Načtení, úprava, smazání

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

Statistiky

GET /api/my/links/{code}/stats

Vrací lidská kliknutí za posledních 90 dní a za celou dobu, kliknutí po dnech a nejčastější země, zdroje odkazů, zařízení, prohlížeče a operační systémy. Roboti a náhledy odkazů (Slack, WhatsApp a podobně) se počítají zvlášť v botClicks. Výsledky jsou v cache asi 5 minut.

Chyby

Chyby používají HTTP stavové kódy a tělo v JSON:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

• 400 neplatný vstup (invalid_url, invalid_slug, …)
• 401 chybějící, neplatný nebo zrušený klíč
• 409 vlastní odkaz už je obsazený
• 422 cíl není povolen (destination_blocked)
• 429 dosažen limit požadavků nebo denní limit

Strojově čitelný popis všech endpointů najdete na /openapi.json.