API-Dokumentation

Erste Schritte

Alle Anfragen laufen über die Basis-URL https://shortit.fr/api/v1, per HTTPS. Anfragekörper werden als JSON gesendet, mit dem Header Content-Type: application/json und dem Header Content-Length (curl setzt beide selbst). Die Felder stehen in snake_case, Datumsangaben im Format ISO 8601 in UTC.

Version 1. In Version 1 wird ein Feld nie entfernt, umbenannt oder in seinem Typ geändert; es können Felder hinzukommen, ignorieren Sie daher Felder, die Sie nicht kennen. Eine inkompatible Änderung erhielte eine neue Adresse (/api/v2), und Version 1 bliebe verfügbar. Eine Anfrage mit einem unbekannten Feld wird abgelehnt (400): Das ist gewollt, damit ein Tippfehler nicht unbemerkt bleibt.

Die OpenAPI-Spezifikation, aus dem Code generiert, ist öffentlich: /api/v1/openapi.json. Es wird nie eine IP-Adresse zurückgegeben oder gespeichert.

curl https://shortit.fr/api/v1/me \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "email": "camille@example.com",
  "links": 6,
  "links_limit": 1000
}

Authentifizierung

Jede Anfrage muss Ihren Schlüssel im Header Authorization tragen, mit vorangestelltem „Bearer“. Ein widerrufener, fehlerhafter oder fehlender Schlüssel führt zu einem 401-Fehler. Ein Schlüssel wird nie in der Adresse übermittelt, und die API liest keine Cookies.

Schlüssel werden in den Einstellungen erstellt (höchstens 5). Ein Schlüssel wird nur einmal angezeigt, bei seiner Erstellung: Nur sein Fingerabdruck wird gespeichert. Er läuft nicht ab: Er gilt bis zum Widerruf, der sofort wirksam ist. Schlüssel beginnen mit shortit_.

Legen Sie einen Schlüssel niemals in öffentlichem Code oder im Browser ab: Verwenden Sie ihn von einem Server oder einem Skript aus. Die API sendet keine CORS-Header. Das Konto muss eine bestätigte Adresse haben und darf nicht gesperrt sein.

curl https://shortit.fr/api/v1/links \
  -H "Authorization: Bearer shortit_…"

{
  "error": {
    "code": "unauthorized",
    "message": "Clé absente ou révoquée."
  }
}

Einen Link erstellen

Felder des Körpers: destination (erforderlich, http oder https, höchstens 2.048 Zeichen); alias (3 bis 32 Buchstaben, Ziffern oder Bindestriche, wird generiert, wenn weggelassen); title (höchstens 120 Zeichen); expires_at (ISO-8601-Datum in der Zukunft); password (6 bis 128 Zeichen, wird nie zurückgegeben: Die Antwort zeigt nur has_password); domain (eine Ihrer aktiven eigenen Domains, siehe Meine Domains; fehlt es: shortit.fr).

Die Ziele werden wie in der Oberfläche geprüft: Private Adressen, reine IP-Adressen, andere Link-Kürzer und als gefährlich gemeldete Websites werden abgelehnt (422). Die Erstellungsgrenzen sind dieselben wie in der Oberfläche: 10 pro Stunde und 50 pro Tag, danach 429.

Pro-Angebot: max_clicks (1 bis 10 000 000) begrenzt die Anzahl der Klicks; sobald das Limit erreicht ist, antwortet der Link wie ein abgelaufener Link. Die Antwort enthält max_clicks und remaining_clicks (null ohne Limit). Ein kostenloses Konto, das max_clicks sendet, erhält 403 pro_required.

curl -X POST https://shortit.fr/api/v1/links \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://exemple-atelier.fr/inscriptions/printemps-2026","alias":"atelier26","title":"Atelier printemps"}'

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "active",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Einen Link lesen

Ein Link wird über seinen Alias bezeichnet, ohne Beachtung der Groß- und Kleinschreibung. Zwei Domains können denselben Alias tragen: Für einen Link auf einer Ihrer eigenen Domains fügen Sie beim Lesen, Ändern, Löschen oder Abrufen der Statistiken den Parameter domain hinzu (zum Beispiel ?domain=go.monsite.fr); ohne ihn ist es der Link auf shortit.fr. Ein Link eines anderen Kontos und ein nicht vorhandener Link erhalten dieselbe Antwort: 404 not_found.

curl https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "active",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Meine Links auflisten

Vom neuesten zum ältesten, per Cursor: Solange next nicht null ist, übergeben Sie seinen Wert im Parameter cursor, um die nächste Seite zu erhalten. Der Cursor ist undurchsichtig; er bleibt gültig, auch wenn zwischen zwei Seiten Links erstellt oder gelöscht werden. Parameter: limit (1 bis 100, standardmäßig 20), cursor, status (active, disabled, expired oder flagged).

curl "https://shortit.fr/api/v1/links?status=active&limit=20" \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "data": [
    {
      "alias": "atelier26",
      "domain": "shortit.fr",
      "short_url": "https://shortit.fr/atelier26",
      "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
      "title": "Atelier printemps",
      "status": "active",
      "expires_at": null,
      "has_password": false,
      "created_at": "2026-09-14T09:12:00.000Z",
      "max_clicks": null,
      "remaining_clicks": null,
      "tags": []
    }
  ],
  "next": null
}

Ändern

Änderbare Felder: destination, title (null löscht ihn), expires_at (null entfernt es), password (ein Text ändert es, null entfernt es) und status (active oder disabled). Nur die gesendeten Felder ändern sich. Der Alias ändert sich nie. Ein gemeldeter Link kann nicht geändert werden (409 link_flagged), und ein aus Sicherheitsgründen deaktivierter Link wird nicht reaktiviert (409 link_locked).

Pro-Angebot: max_clicks setzt oder ändert das Klicklimit, und sein Zähler beginnt dann wieder bei null (wer das Limit eines Links anhebt, der es erreicht hatte, nimmt ihn wieder in Betrieb); null entfernt das Limit.

Pro-Tarif: Weiterleitungsregeln (höchstens 5) werden mit GET /api/v1/links/ALIAS/rules gelesen und mit PUT auf derselben Adresse ersetzt, mit dem Body {"rules":[{"type":"country","value":"FR","destination":"https://…"}]}. type ist country (ISO-Ländercode, „FR“) oder device (mobile, tablet oder desktop); die erste Regel, die auf den Besucher passt, gewinnt, andernfalls gilt das Ziel des Links. Jedes Ziel wird wie das des Links geprüft (422). Bei einem Link mit 100 oder mehr Klicks erfolgt die Änderung im Dashboard (403 confirmation_required).

curl -X PATCH https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

{
  "alias": "atelier26",
  "domain": "shortit.fr",
  "short_url": "https://shortit.fr/atelier26",
  "destination": "https://exemple-atelier.fr/inscriptions/printemps-2026",
  "title": "Atelier printemps",
  "status": "disabled",
  "expires_at": null,
  "has_password": false,
  "created_at": "2026-09-14T09:12:00.000Z",
  "max_clicks": null,
  "remaining_clicks": null,
  "tags": []
}

Löschen

curl -X DELETE https://shortit.fr/api/v1/links/atelier26 \
  -H "Authorization: Bearer VOTRE_CLE"

(leerer Körper)

Statistiken eines Links

Die letzten 30 Tage (Tage in Europe/Paris, vom ältesten bis heute) und die Gesamtzahl seit der Erstellung. unique_visitors ist die Summe der eindeutigen Besucher jedes Tages: Ein Besucher, der an drei Tagen wiederkommt, zählt dreimal (es wird keine dauerhafte Kennung gespeichert). variation_pct vergleicht mit dem vorherigen Zeitraum und ist null, wenn es ihn nicht gibt.

Jede Aufteilung (countries, referrers, devices, browsers) ist nach Klicks absteigend sortiert und auf 5 Zeilen begrenzt. value ist der Ländercode, die Herkunftsdomain, das Gerät oder der Browser; null bedeutet „unbekannt“ oder, mit other auf true, „andere“ (die seltensten Werte, zusammengefasst).

curl https://shortit.fr/api/v1/links/atelier26/stats \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "alias": "atelier26",
  "period_days": 30,
  "clicks": 1397,
  "unique_visitors": 1006,
  "total_clicks": 2310,
  "variation_pct": 12.4,
  "days": [
    {
      "date": "2026-09-12",
      "clicks": 61
    },
    {
      "date": "2026-09-13",
      "clicks": 48
    }
  ],
  "countries": [
    {
      "value": "FR",
      "clicks": 925
    },
    {
      "value": "BE",
      "clicks": 201
    },
    {
      "value": null,
      "clicks": 271,
      "other": true
    }
  ],
  "referrers": [
    {
      "value": "instagram.com",
      "clicks": 512
    },
    {
      "value": null,
      "clicks": 885
    }
  ],
  "devices": [
    {
      "value": "mobile",
      "clicks": 944
    },
    {
      "value": "desktop",
      "clicks": 453
    }
  ],
  "browsers": [
    {
      "value": "Safari",
      "clicks": 601
    },
    {
      "value": "Chrome",
      "clicks": 796
    }
  ]
}

Meine Domains

Zustand jeder Domain: pending_dns (wartet auf Ihre DNS-Einträge), verified (Inhaberschaft bestätigt), cert_pending (Zertifikat in Arbeit), active (die Domain leitet weiter), error (die Prüfung ist fehlgeschlagen oder wurde abgebrochen), disabled (deaktiviert: Ein Eintrag ist verschwunden, oder Entscheidung der Administration).

curl https://shortit.fr/api/v1/domains \
  -H "Authorization: Bearer VOTRE_CLE"

{
  "data": [
    {
      "name": "go.camille.fr",
      "status": "active",
      "created_at": "2026-09-02T08:00:00.000Z"
    },
    {
      "name": "liens.exemple-asso.fr",
      "status": "pending_dns",
      "created_at": "2026-09-14T09:12:00.000Z"
    }
  ]
}

Grenzen und Fehler

Jeder Schlüssel ist auf 30 Anfragen pro Minute begrenzt (300 mit dem Pro-Angebot, in Kürze). Darüber hinaus antwortet die API mit 429 und dem Header Retry-After, der in Sekunden die Wartezeit bis zum nächsten Versuch angibt. Dreißig abgelehnte Schlüssel innerhalb einer Minute von derselben Adresse führen dazu, dass diese Adresse für den Rest der Minute abgelehnt wird.

Jeder Fehler hat denselben Körper: { "error": { "code", "message" } }, mit zusätzlich field und reason bei einer Validierungsablehnung (422). Der Code ist stabil; die Meldung richtet sich an eine Person und kann sich ändern. Codes:

unauthorized (401): Clé absente, mal formée ou révoquée.

email_not_verified (403): L'adresse e-mail du compte n'est pas vérifiée.

account_suspended (403): Le compte est suspendu.

link_limit_reached (403): Le plafond de liens du compte est atteint.

pro_required (403): Cette fonction (limite de clics, règles de redirection…) est réservée aux comptes de l'offre Pro.

confirmation_required (403): Ce lien a beaucoup de clics : changer sa destination ou ses règles de redirection, ou le supprimer, se fait depuis le tableau de bord, avec un code reçu par e-mail.

not_found (404): Lien introuvable, ou qui n'est pas à vous.

link_flagged (409): Le lien est signalé : il ne se modifie ni ne se supprime.

link_locked (409): Le lien a été désactivé pour un motif de sécurité : il ne se réactive pas.

invalid_json (400): Le corps n'est pas du JSON valide.

invalid_request (400): Requête invalide : champ inconnu, type inattendu ou paramètre hors limites.

validation_failed (422): Une valeur est refusée : le corps porte field et reason.

payload_too_large (413): Corps de plus de 16 Ko.

length_required (411): L'en-tête Content-Length est obligatoire avec un corps.

unsupported_media_type (415): Content-Type : application/json obligatoire avec un corps.

rate_limited (429): Plus de requêtes par minute que l'offre ne le permet (30 en gratuit, 300 en Pro) avec cette clé : voir Retry-After.

internal_error (500): Erreur du serveur. Réessayez ; elle ne détaille rien.

{
  "error": {
    "code": "rate_limited",
    "message": "Trop de requêtes. Réessayez dans 12 secondes."
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Déjà pris, choisissez-en un autre.",
    "field": "alias",
    "reason": "taken"
  }
}