SHORTCLIX REST-API – Benutzerhandbuch

Mit der SHORTCLIX-REST-API kannst du deine Projekte und Kurzlinks verwalten, QR-Codes erstellen und Klickstatistiken direkt aus deinen eigenen Skripten, Automatisierungen (Zapier, Make, n8n …) oder KI-Tools abrufen.

Verfügbarkeit: Die API ist Teil der Tarife „Basic“ und „Pro “. Im „Free“-Tarif ist sie nicht verfügbar. Jedes Token gehört zu einem Arbeitsbereich, und alle Tarifbeschränkungen dieses Arbeitsbereichs gelten für die API genauso wie im Dashboard.

• Basis-URL: https://shortclix.com/api/v1
• Format: JSON. Immer senden Accept: application/json.
• Auth: Bearer-Token (siehe Authentifizierung).

Inhaltsverzeichnis

1. Authentifizierung
2. Grundlagen von Anfrage und Antwort
3. Ratenbegrenzungen
4. Fehler
5. Projekte
6. Kurzlinks
7. QR-Codes
8. Analytik
9. Vollständiges Beispiel: Einen Link von Anfang bis Ende verfolgen
10. Feldreferenz

Authentifizierung

1. Ein Token erstellen

1. Öffne dein Dashboard und wechsle zu dem Arbeitsbereich, den das Token steuern soll.
2. Geh zu den Arbeitsbereichseinstellungen. (Nur Arbeitsbereichsinhaber können Tokens verwalten.)
3. Im API-Token Gib im entsprechenden Feld einen Namen ein (z. B. Zapier, MCP-Client), wähle die Berechtigungen aus und klicke auf Token erstellen.
4. Kopiere das Token sofort – es wird nur einmal angezeigt. Falls du es verlierst, widerrufe es und erstelle ein neues.

Der Abschnitt „API-Token“ wird nur angezeigt, wenn dein Tarif den API-Zugang beinhaltet.

Token-Format: Ein Token sieht so aus: 2|KwCUgJwAg3UqqaBVlpO…. Der führende 2| (eine Zahl, gefolgt von einem Pipe-Zeichen) ist ein normaler Bestandteil des Tokens — Kopiere den gesamten Text und schick ihn ab. Tokens können nach ihrer Erstellung nicht wiederhergestellt werden; wenn du eines verlierst, widerrufe es und erstelle ein neues.

Berechtigungen (Gültigkeitsbereiche)

Wähle die geringstmögliche Berechtigung, die du brauchst. Mit einem Lesezugriffstoken kannst du nichts ändern.

2. Das Token senden

Übermittle das Token bei jeder Anfrage als Bearer-Token:

curl https://shortclix.com/api/v1/projects \
  -H "Authorization: Bearer DEIN_TOKEN_HIER" \
  -H "Accept: application/json"

Ein Token ist an den Arbeitsbereich gebunden, in dem es erstellt wurde. Es kann niemals Daten in einem anderen Arbeitsbereich einsehen oder ändern, selbst wenn du mehreren angehörst.

3. Ein Token widerrufen

Klicke unter „Workspace-Einstellungen“ → „API-Token“ neben einem beliebigen Token auf „Widerrufen “. Anwendungen, die dieses Token nutzen, verlieren sofort den Zugriff.

Grundlagen von Anfrage und Antwort

• Sende Anfrageinhalte als JSON (Content-Type: application/json) für POST/PATCH.

• Einzelne Ressourcen werden in ein Daten Objekt; Sammlungen in einem Daten Array:

  { "data": { "id": 1, "name": "Launch Campaign" } }
  

• IDs: Projekte können anhand ihrer Nummer angesprochen werden id oder ihre slug. Kurzlinks werden über ihre short_code (siehe Einen Link erkennen).

• Zeitstempel werden im ISO-8601-Format zurückgegeben (07.06.2026, 14:30:00 Uhr (UTC)).

• Endpunkte zum Auflisten geben alle passenden Datensätze zurück (keine Paginierung).

Ratenbegrenzungen

Jedes Token ist begrenzt auf 60 Anfragen pro Minute. Wird dieser Wert überschritten, wird HTTP 429. Standard X-RateLimit-Limit / X-RateLimit-Remaining In jeder Antwort sind Header enthalten.

Fehler

Die API verwendet herkömmliche HTTP-Statuscodes und einen JSON-Body mit einem Nachricht.

Beispiel für einen Validierungsfehler:

{
  "message": "The original url field is required.",
  "errors": { "original_url": ["The original url field is required."] }
}

Beispiel für einen Plan-Limit-Fehler (du hast die maximale Anzahl an Projekten/Links für deinen Plan erreicht):

{
  "message": "Your plan does not allow creating more short links.",
  "plan_limit_reached": true
}

Projekte

Ein Projekt fasst deine Kurzlinks zusammen.

Projekte auflisten

GET /api/v1/projects

{
  "data": [
    {
      "id": 1,
      "name": "Launch Campaign",
      "slug": "launch-campaign",
      "description": null,
      "monthly_report_recipients": null,
      "weekly_report_recipients": null,
      "short_links_count": 4,
      "created_at": "2026-06-01T09:00:00+00:00",
      "updated_at": "2026-06-01T09:00:00+00:00"
    }
  ]
}

Ein Projekt erstellen

POST /api/v1/projects

curl -X POST https://shortclix.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Launch Campaign"}'

Rücksendungen 201 mit dem erstellten Projekt. Gibt zurück 422 mit plan_limit_erreicht falls du das Projektlimit deines Tarifs erreicht hast.

Anzeigen / Aktualisieren / Löschen

GET    /api/v1/projects/{id-or-slug}
PATCH  /api/v1/projects/{id-or-slug}
DELETE /api/v1/projects/{id-or-slug}

PATCH akzeptiert jede Teilmenge der „create“-Felder. LÖSCHEN Ergebnisse 204 und löscht das Projekt sowie alle dazugehörigen Kurzlinks.

Kurzlinks

Links auflisten

GET /api/v1/links                          # alle Links im Arbeitsbereich
GET /api/v1/projects/{id-or-slug}/links    # Links eines Projekts

{
  "data": [
    {
      "id": 10,
      "project_id": 1,
      "short_code": "launch",
      "short_url": "https://shortclix.com/launch",
      "original_url": "https://example.com/my-long-link",
      "title": "Launch link",
      "is_active": true,
      "is_effectively_active": true,
      "redirect_url": null,
      "expires_at": null,
      "created_at": "2026-06-02T12:00:00+00:00",
      "updated_at": "2026-06-02T12:00:00+00:00"
    }
  ]
}

is_effectively_active ist false de wenn der Link deaktiviert ist oder dessen expires_at ist vorbei.

Link erstellen

POST /api/v1/projects/{id-oder-slug}/links

curl -X POST https://shortclix.com/api/v1/projects/launch-campaign/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "original_url": "https://example.com/my-long-link",
        "title": "Launch link",
        "short_code": "launch"
      }'

Rücksendungen 201 mit dem Link (einschließlich short_url). Rückgaben 422 mit plan_limit_erreicht Wenn du das Link-Limit deines Tarifs erreicht hast oder ein Validierungsfehler bei einem reservierten/doppelten Link auftritt short_code („Dieser Kurznummer ist bereits vergeben.“) oder eine ungültige original_url.

Sicherheit am Reiseziel: Jede Ziel-URL wird kurz nach der Erstellung des Links oder dessen original_url wird geändert. Wenn ein Ziel als unsicher eingestuft wird, wird der Kurzlink deaktiviert und die Weiterleitung wird beendet (Besucher sehen eine „gesperrte“ Seite); der Inhaber des Arbeitsbereichs wird per E-Mail benachrichtigt. Die Erstellung selbst liefert weiterhin 201 — Die Überprüfung läuft im Hintergrund — richte Links daher immer auf seriöse Ziele, die du selbst kontrollierst.

Einen Link erkennen

Für „Anzeigen“, „Aktualisieren“, „Löschen“, „QR“ und „Analysen“ kannst du einen Link auf eine von zwei Arten identifizieren:

• Per Kurzwahl (empfohlen) – füge es dem Pfad hinzu: GET /api/v1/links/launch
• Nach Ziel-URL – weiter ?original_url= im Abfrage-String und verwende einen beliebigen Platzhalter (z. B. -) für das Wegsegment: GET /api/v1/links/-?original_url=https%3A%2F%2Fexample.com%2Fmy-long-link Wenn die URL übereinstimmt mehr als eins Link, die API gibt Folgendes zurück: 409; benutze stattdessen den Kurzcode.

Link aktualisieren / löschen

PATCH  /api/v1/links/{short-code}
DELETE /api/v1/links/{short-code}

PATCH akzeptiert jede Teilmenge der „create“-Felder (z. B. „change“ original_url, is_active, expires_at). LÖSCHEN Ergebnisse 204.

QR-Codes

GET /api/v1/links/{short-code}/qr

Gibt den QR-Code des Links als SVG-Bild (Content-Type: image/svg+xml), die die Kurz-URL kodiert.

curl https://shortclix.com/api/v1/links/launch/qr \
  -H "Authorization: Bearer DEIN_TOKEN" \
  -o launch-qr.svg

Du kannst den Link auch anhand der Ziel-URL identifizieren, und zwar über ?original_url= (siehe oben).

Analytik

Alle Analyse-Endpunkte geben aggregierte Zahlen zurück (keine Diagrammreihen). Die Werte spiegeln das Zeitfenster deines Tarifs wider.

Arbeitsbereich-Analysen (alle Projekte)

GET /api/v1/analytics

{
  "data": {
    "generated_at": "2026-06-07T14:30:00+00:00",
    "projects": [
      {
        "id": 1,
        "name": "Launch Campaign",
        "slug": "launch-campaign",
        "stats": {
          "current_month": 320,
          "previous_month": 540,
          "mom_change": -12.5,
          "yoy_change": null
        }
      }
    ]
  }
}

Projektanalysen (alle Links eines Projekts)

GET /api/v1/projects/{id-or-slug}/analytics

Gibt das Projekt plus ein Links Array, jeweils mit demselben Statistiken Form wie oben.

Link-Analyse (mit Datumsbereich)

GET /api/v1/links/{short-code}/analytics?dateFrom=2026-05-01&dateTo=2026-06-07&timezone=Europe/Vienna

{
  "data": {
    "generated_at": "2026-06-07T14:30:00+00:00",
    "link": { "id": 10, "short_code": "launch", "title": "Launch link", "original_url": "https://example.com/my-long-link" },
    "date_from": "2026-05-01",
    "date_to": "2026-06-07",
    "timezone": "Europe/Vienna",
    "period_stats": {
      "total": 860,
      "previous_total": 540,
      "mom_change": 59.3,
      "previous_out_of_range": false,
      "yoy_total": null,
      "yoy_change": null,
      "yoy_out_of_range": null
    },
    "referrers": [ { "referrer": "https://t.co/", "total": 120 } ],
    "countries": [ { "code": "AT", "label": "Austria", "total": 300, "pct": 34.9 } ],
    "languages": [ { "code": "de", "label": "German", "total": 280, "pct": 32.6 } ],
    "devices": [ { "code": "mobile", "label": "Mobile", "total": 500, "pct": 58.1 } ],
    "operating_systems": [ { "code": "ios", "label": "iOS", "total": 240, "pct": 27.9 } ],
    "browsers": [ { "code": "chrome", "label": "Chrome", "total": 410, "pct": 47.7 } ],
    "day_of_week": [ { "day": "Mon", "total": 130, "pct": 15.1 } ],
    "hours": [ { "hour": "09:00", "total": 70, "pct": 8.1 } ]
  }
}

Die Aufschlüsselungen sind sortiert nach insgesamt absteigend. Klicks ohne bekannten Wert werden als „unbestätigte“ Zeile zusammengefasst. pct ist der Anteil an der Gesamtsumme des Zeitraums.

Vollständiges Beispiel: Einen Link von Anfang bis Ende verfolgen

Das entspricht einem typischen Automatisierungs-/KI-Ablauf: Eine URL kürzen, den dazugehörigen QR-Code abrufen und später die Klicks auswerten.

TOKEN="YOUR_TOKEN"
BASE="https://shortclix.com/api/v1"

# 1. Create the short link in a project
curl -s -X POST "$BASE/projects/launch-campaign/links" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"original_url": "https://example.com/my-long-link", "title": "My link"}'
# → { "data": { "short_code": "a1b2c3", "short_url": "https://shortclix.com/a1b2c3", ... } }

# 2. Download its QR code
curl -s "$BASE/links/a1b2c3/qr" -H "Authorization: Bearer $TOKEN" -o my-link-qr.svg

# 3. Later: how many clicks this month?
curl -s "$BASE/links/a1b2c3/analytics" -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

Feldreferenz

Projekt

Kurzlink

Klickstatistiken (Statistiken)

Über MCP verbinden

SHORTCLIX spricht auch MCP (Model Context Protocol), sodass KI-Assistenten (Claude und andere MCP-fähige Clients) deine Links verwalten und Analysedaten in natürlicher Sprache auswerten können – „Diesen Link verfolgen“, „Wie viele Klicks hat er bekommen?“. MCP ist verfügbar auf der Basic und Pro Pläne. Eine vollständige Schritt-für-Schritt-Anleitung zur Einrichtung (Claude Code, Claude Desktop, lokal vs. Produktionsumgebung) findest du unter /docs/mcp.

• Endpunkt: https://shortclix.com/mcp
• Auth: dieselben Tokens wie bei der REST-API (erstellt unter „Workspace-Einstellungen“ → „API-Tokens“). Verwende ein Lese- und Schreib-Token, wenn der Assistent Links erstellen oder ändern soll; ein Nur-Lese-Token beschränkt ihn auf Auflistungen und Analysen.

Client-Konfiguration

Die meisten MCP-Clients akzeptieren einen HTTP-Server-Eintrag wie diesen (ersetze den Platzhalter durch eines deiner Tokens):

{
  "mcpServers": {
    "shortclix": {
      "type": "http",
      "url": "https://shortclix.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Der genaue Speicherort der Konfiguration hängt von deinem Client ab. Im Dashboard wird dieser Ausschnitt in den Workspace-Einstellungen bereits mit deinem Endpunkt ausgefüllt angezeigt.

Verfügbare Tools

Der Assistent erhält den vollständigen Satz, der die REST-API widerspiegelt:

• Projekte: list_projects, create_project, update_project, Projekt löschen
• Kurzlinks: list_short_links, create_short_link, update_short_link, delete_short_link, get_qr_code
• Analytik: get_workspace_analytics, get_project_analytics, get_link_analytics

Alles ist auf den Arbeitsbereich des Tokens beschränkt und unterliegt den Beschränkungen deines Tarifs. Zum Erstellen, Aktualisieren und Löschen benötigst du ein Lese- und Schreib-Token.

Hast du Fragen oder möchtest du höhere Limits? Dann wende dich an den Support unter hello@shortclix.com.