REST API · v1

API-Dokumentation

URLs kürzen, Analysen abrufen und Links programmatisch verwalten. Alle Endpunkte geben JSON zurück und erfordern ein Bearer-Token.

Kostenlosen API-Zugang erhalten
Basis-URL: https://urlly.me/api/v1
POST

/api/v1/shorten

URL kürzen

 GET

/api/v1/stats/{hash}

Link-Analysen abrufen

 GET

/api/v1/links

Alle Links anzeigen

 —

domain_id param

Eigene Domain verwenden

Authentifizierung

Senden Sie Ihr Token im Authorization-Header bei jeder Anfrage

HeaderWert
AuthorizationBearer <token>
Acceptapplication/json
Content-Typeapplication/json (Nur POST)

Generieren Sie Token in Ihren API-Einstellungen. Token werden nur einmal angezeigt — bewahren Sie sie sicher auf. Fehlende oder ungültige Token geben 401 Unauthorized zurück.

bash 
# Save your token in an environment variable
export URLLY_TOKEN="your_token_here"

# Include it in every request
curl https://urlly.me/api/v1/shorten \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
POST /api/v1/shorten 201 Created

URL kürzen. Optional einen benutzerdefinierten Alias (3–20 Zeichen) und eine verifizierte eigene Domain angeben.

Anfragebody

FeldTypErforderlichHinweise
long_url string Ja Gültige URL, max. 2048 Zeichen
custom_alias string Nein [a-z0-9_-], 3–20 Zeichen
domain_id integer Nein ID einer verifizierten eigenen Domain. Weglassen für Standard-Domain.

Antwort

201 Created 
{
  "success": true,
  "short_url": "https://urlly.me/my-link",
  "original_url": "https://example.com/...",
  "hash": "my-link",
  "created_at": "2026-03-19T10:00:00+00:00"
}

Beispielanfrage

bash 
# Auto-generated short code
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url":"https://example.com/long-page"}'

# With custom alias
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "custom_alias": "my-link"
  }'
GET /api/v1/stats/{hash} 200 OK

Klick-Analysen für einen Ihrer Links — Gesamtklicks, tägliche Aufschlüsselung, Geräteaufteilung, Top-Browser.

URL-Parameter

ParameterBeschreibung
hash Der Kurzcode oder Alias Ihres Links

Antwort

200 OK 
{
  "success": true,
  "hash": "aBcDeFg",
  "short_url": "https://urlly.me/aBcDeFg",
  "original_url": "https://example.com",
  "is_active": true,
  "stats": {
    "total_clicks": 142,
    "clicks_by_day": [
      { "date": "2026-03-19", "total": 108 }
    ],
    "devices": { "desktop": 80, "mobile": 62 },
    "browsers": { "Chrome": 95, "Safari": 47 }
  }
}

Beispielanfrage

bash 
curl -X GET \
  "https://urlly.me/api/v1/stats/aBcDeFg" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

Eigene Domains

Kurz-Links über Ihre eigene Domain statt der Standard-Domain bereitstellen

Authentifizierte Benutzer können verifizierte eigene Domains hinzufügen. Übergeben Sie nach der Verifizierung domain_id an den Endpunkt POST /shorten, um Kurz-Links unter dieser Domain zu erstellen.

Einrichtung

  1. 1.Gehen Sie zu Eigene Domains in Ihrem Dashboard und fügen Sie Ihre Domain hinzu.
  2. 2.Fügen Sie einen DNS-CNAME-Eintrag hinzu, der Ihre Subdomain auf urlly.me zeigt.
  3. 3.Fügen Sie den im Dashboard angezeigten TXT-Verifizierungseintrag hinzu und klicken Sie auf Verifizieren.
  4. 4.Nach der Verifizierung notieren Sie die id der Domain und übergeben Sie diese als domain_id in API-Aufrufen.
Kurzcodes sind pro Domain eindeutig. Derselbe Alias kann gleichzeitig auf Ihrer eigenen Domain und der Standard-Domain existieren.

Beispiel: Kürzen mit eigener Domain

bash 
# Shorten using your custom domain (id: 3)
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "domain_id": 3
  }'

# Response — short_url uses your domain
{
  "success": true,
  "short_url": "https://links.yourdomain.com/aBcDeFg",
  "original_url": "https://example.com/long-page",
  "hash": "aBcDeFg",
  "created_at": "2026-03-21T10:00:00+00:00"
}

Ratenbegrenzung

2000 Anfragen pro 1 Min. pro Token

Antwort-HeaderBeschreibung
X-RateLimit-LimitMax. Anfragen pro Zeitfenster (2000)
X-RateLimit-RemainingVerbleibende Anfragen im aktuellen Fenster
Retry-AfterSekunden bis zum Reset des Fensters (nur 429)
Bei Überschreitung geben Anfragen 429 Too Many Requests zurück. Prüfen Sie Retry-After für den Wiederholungszeitpunkt.

429 Antwort

429 Too Many Requests 
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 0
Retry-After: 47

{
  "message": "Too Many Attempts."
}

Fehlercodes

Alle Fehler geben JSON mit einem message-Feld zurück. Validierungsfehler (422) enthalten auch ein errors-Objekt.

StatusBedeutungHäufige Ursache
401 Nicht autorisiert Fehlendes oder ungültiges Token
403 Verboten Ressource gehört Ihnen nicht
404 Nicht gefunden Link-Hash existiert nicht
422 Validierungsfehler Ungültige Felder oder doppelter Alias
429 Zu viele Anfragen Ratenbegrenzung überschritten
500 Serverfehler Ein Fehler ist auf unserer Seite aufgetreten

Fehler-Antwortbeispiele

JSON 
# 401 Unauthorized
{ "message": "Unauthenticated." }

# 404 Not Found
{
  "error": "not_found",
  "message": "Link not found or does not belong to you."
}

# 422 Validation Error
{
  "message": "The long_url field is required.",
  "errors": {
    "long_url": [ "The long_url field is required." ]
  }
}

# 422 Unsafe URL
{
  "error": "unsafe_url",
  "message": "This URL has been flagged as unsafe."
}

Bereit zu entwickeln?

Generieren Sie ein Token und führen Sie Ihren ersten API-Aufruf in Sekunden durch.

Kostenloses Konto erstellen Anmelden