📘

API-Dokumentation

Diese Seite beschreibt die ShortBoost-API für KI-Assistenten und Automationen. Einen Schlüssel legst du unter API-Schlüssel an.

Grundlagen

Adresse: https://api.shortboost.one/api/v1
Anmeldung: Header Authorization: Bearer sbo_live_… (nie als URL-Parameter)
Format: JSON, bei POST/PATCH mit Content-Type: application/json
Limit: 60 Anfragen pro Minute und Schlüssel
Erster Aufruf: GET /key-info zeigt Konto, Tarif, Rechte und Anzahl der Links

curl -H "Authorization: Bearer sbo_live_…" https://api.shortboost.one/api/v1/key-info

Links

Aufruf	Recht	Zweck
`GET /links`	links.read	Liste. Parameter: `page`, `limit` (max. 100), `search`, `project_id`, `category_id` (`none` = ohne), `favorite=true`, `sort` (`created_desc`, `created_asc`, `clicks_desc`, `clicks_asc`, `name_asc`, `name_desc`)
`GET /links/{id}`	links.read	ein Link
`GET /links/check-slug/{slug}`	links.read	ist die Kurzadresse frei? `{"available":true}`
`GET /links/{id}/qr`	links.read	QR-Code. Parameter: `format=png\|svg`, `size` (100–1000), `color`, `bg` (Hex ohne #)
`POST /links`	links.write	anlegen. Pflicht: `original_url`. Optional: `slug`, `title`, `name`, `notes`, `tags` (Liste), `project_id`, `category_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `expires_at`, `click_limit`, `password`, `smart_routing` (Liste der Regeln, siehe unten)
`PATCH /links/{id}`	links.write	ändern, gleiche Felder wie beim Anlegen, dazu `is_active`, `is_favorite`
`POST /links/bulk`	links.write (bei `delete` zusätzlich links.delete)	`{"action":"activate\|deactivate\|move\|categorize\|favorite\|delete","link_ids":[…],"payload":{…}}`, max. 500 Links
`DELETE /links/{id}`	links.delete	löschen

curl -X POST https://api.shortboost.one/api/v1/links \
  -H "Authorization: Bearer sbo_live_…" \
  -H "Content-Type: application/json" \
  -d '{"original_url":"https://example.com/angebot","title":"Herbstangebot","utm_source":"newsletter"}'

Antwort (gekürzt):

{"link":{"id":"…","slug":"aB3xY9","short_url":"https://shlk.one/aB3xY9","original_url":"https://example.com/angebot","title":"Herbstangebot","click_count":0,"has_password":false,"smart_routing":[],"is_active":true,"created_at":"…"}}

Smart Routing (`smart_routing`)

Mit Smart Routing leitet ein Link Besucher je nach Land, Sprache, Betriebssystem oder Gerät auf ein anderes Ziel. Die Regeln werden von oben nach unten geprüft, die erste passende gewinnt. Passt keine, gilt original_url. Mehr dazu im Artikel Smart Routing. Nur im Pro- und Lifetime-Tarif (sonst 402).

Feld je Regel	Bedeutung
`url`	Pflicht. Ziel dieser Regel, `http://` oder `https://`
`name`	optional, max. 60 Zeichen (erscheint in der Statistik)
`country`	Länder als ISO-Code in Großbuchstaben, z. B. `["AT","DE","CH"]`
`language`	Browsersprache als ISO-Code in Kleinbuchstaben, z. B. `["de","en"]`
`os`	`ios`, `android`, `windows`, `macos`, `linux`
`device`	`mobile`, `tablet`, `desktop`
`id`	vergibt der Server. Bei neuen Regeln weglassen, bei bestehenden unverändert mitschicken, sonst beginnt die Statistik dieser Regel neu

Jede Regel braucht eine url und mindestens eine Bedingung. Zwischen den Bedingungen gilt UND, zwischen mehreren Werten einer Bedingung ODER. Eine leere Bedingung heißt „egal".
Höchstens 10 Regeln pro Link. Die Reihenfolge der Liste ist die Prüfreihenfolge.
PATCH mit smart_routing ersetzt alle Regeln. [] oder null löscht alle Regeln. Ohne das Feld bleiben sie unverändert.
In Antworten steht smart_routing immer als Liste, ohne Regeln als [].

Beispiel: App-Link, der iPhones in den App Store und Android-Geräte zu Google Play schickt. Alle anderen landen auf der Webseite.

curl -X PATCH https://api.shortboost.one/api/v1/links/{id}   -H "Authorization: Bearer sbo_live_…"   -H "Content-Type: application/json"   -d '{"original_url":"https://example.com/app",
       "smart_routing":[
         {"name":"iPhone","url":"https://apps.apple.com/app/id123456789","os":["ios"]},
         {"name":"Android","url":"https://play.google.com/store/apps/details?id=com.example.app","os":["android"]}
       ]}'

Statistiken

Aufruf	Zweck
`GET /analytics/overview?days=30`	Gesamtklicks, Links, Top-Links
`GET /analytics/dashboard`	Kennzahlen, Klicks pro Tag, Browser, Quellen, Geräte, Länder. Parameter `from`, `to` (ISO-Datum)
`GET /analytics/links/{id}`	Auswertung eines Links, gleiche Parameter. Enthält `routing`: Klicks pro Smart-Routing-Regel, z. B. `[{"route_id":"a1b2c3d4e5","clicks":12},{"route_id":null,"clicks":40}]`. `route_id` ist die `id` der Regel, `null` heißt: keine Regel hat gepasst (normales Ziel)
`GET /analytics/clicks?days=30`	Klicks über die Zeit
`GET /analytics/geo?days=30`	Länder und Städte
`GET /analytics/devices?days=30`	Geräte, Browser, Betriebssysteme
`GET /analytics/utm?days=30`	UTM-Quellen, -Medien, -Kampagnen
`GET /analytics/heatmap`, `/analytics/heatmap/{id}`	Klicks nach Wochentag und Uhrzeit

Alle Statistik-Aufrufe brauchen stats.read.

Projekte und Kategorien

Aufruf	Recht
`GET /projects`, `GET /categories` (optional `?project_id=`)	projects.read
`POST /projects` `{"name":"…","color":"#1a56db"}`, `POST /categories` `{"name":"…","project_id":"…"}`	projects.write
`PATCH /projects/{id}`, `PATCH /categories/{id}`	projects.write
`DELETE /projects/{id}` (Links wandern ins Standard-Projekt), `DELETE /categories/{id}`	projects.delete

Fehler

Status	Antwort	Bedeutung
401	`{"error":"invalid_key"}`	Schlüssel falsch, widerrufen, abgelaufen, oder der Aufruf ist über die API nicht erreichbar
402	`{"error":"plan_required"}`	Konto hat keinen Pro- oder Lifetime-Tarif (mehr)
403	`{"error":"missing_scope","required":"links.write"}`	dem Schlüssel fehlt dieses Recht
429	`{"error":"rate_limited"}`	mehr als 60 Anfragen pro Minute; Header `Retry-After` nennt die Wartezeit in Sekunden
400, 404, 409	`{"error":"…"}`	fachlicher Fehler mit deutschem Text, z. B. „Slug bereits vergeben"

Anweisung für eine KI

Du steuerst meinen Linkkürzer ShortBoost über die API https://api.shortboost.one/api/v1
mit dem Header "Authorization: Bearer <SCHLÜSSEL>". Dokumentation: https://shortboost.one/help/api-dokumentation
1. Rufe zuerst GET /key-info auf und prüfe deine Rechte.
2. Lege Links mit POST /links an und gib mir die short_url zurück.
3. Lösche nichts ohne meine ausdrückliche Bestätigung.
4. Bei 429 warte die Sekunden aus dem Header Retry-After ab.

‹ Zur Hilfe-Übersicht