Zum Inhalt springen

Public API

Spurig REST API

Steuere QR-Codes, Kurzlinks, Kampagnen und Analytics programmatisch — z.B. aus einem KI-Agenten, einer n8n-Pipeline oder einem eigenen Backend. Authentifizierung über Bearer-Tokens, die du in den Einstellungen unter Entwickler erstellst.

Authentifizierung

Alle Endpoints erwarten einen Authorization: Bearer spr_live_… Header. Token-Format: spr_live_ + 32 zufällige Zeichen. Ein Token wird genau einmal beim Erstellen angezeigt — danach nur noch der Prefix.

curl https://spurig.com/api/v1/me \
  -H "Authorization: Bearer spr_live_yourTokenHere"

Rate-Limit

100 Requests pro Minute pro Token. Bei Überschreitung kommt 429 mit Retry-After Header in Sekunden.

Response-Format

Erfolg: { "data": ... }, Listen zusätzlich mit { "data": [...], "pagination": { "page", "per_page", "total" } }. Fehler: { "error": { "message": "...", "code": "..." } } mit passendem HTTP-Status (400, 401, 404, 429, 500).

Endpoints

GET/api/v1/me

Aktuelle User-Info zurückgeben.

Beispiel

curl https://spurig.com/api/v1/me \
  -H "Authorization: Bearer spr_live_..."
GET/api/v1/campaigns

Liste aller Kampagnen des Owners. Paginiert.

Query-Parameter

  • page — Seitennummer, Default 1
  • per_page — Einträge pro Seite, 1-100, Default 25

Beispiel

curl https://spurig.com/api/v1/campaigns?page=1 \
  -H "Authorization: Bearer spr_live_..."
POST/api/v1/campaigns

Neue Kampagne anlegen.

Request-Body

{
  "name": "Sommer 2026",
  "description": "Strand-Promo",
  "status": "active",
  "start_date": "2026-06-01",
  "end_date": "2026-08-31"
}

Beispiel

curl -X POST https://spurig.com/api/v1/campaigns \
  -H "Authorization: Bearer spr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Sommer 2026"}'
GET/api/v1/campaigns/{id}

Eine Kampagne lesen.

PATCH/api/v1/campaigns/{id}

Kampagne aktualisieren. Felder: name, slug, description, status, start_date, end_date.

Request-Body

{ "name": "Neuer Name", "status": "archived" }
DELETE/api/v1/campaigns/{id}

Kampagne löschen.

GET/api/v1/qr-codes

Liste aller QR-Codes des Owners.

Query-Parameter

  • page — Seitennummer
  • per_page — Einträge pro Seite (1-100)
  • placement_id — Optionaler Placement-Filter
POST/api/v1/qr-codes

Neuen QR-Code anlegen. short_code wird auto-generiert wenn nicht angegeben.

Request-Body

{
  "target_url": "https://spurig.com/landing",
  "title": "Sommer-Plakat",
  "utm_source": "print",
  "utm_medium": "qr",
  "utm_campaign": "sommer2026",
  "qr_fg_color": "#000000",
  "qr_bg_color": "#FFFFFF"
}

Beispiel

curl -X POST https://spurig.com/api/v1/qr-codes \
  -H "Authorization: Bearer spr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com","title":"Test"}'
GET/api/v1/qr-codes/{id}

Einen QR-Code lesen.

PATCH/api/v1/qr-codes/{id}

QR-Code aktualisieren. Felder: target_url, active, valid_from, valid_until, note, title, utm_*, qr_fg_color, qr_bg_color, max_scans, short_host, placement_id.

DELETE/api/v1/qr-codes/{id}

QR-Code löschen.

GET/api/v1/qr-codes/{id}/png

Live-PNG des QR-Codes. Query "size" (64-2048, Default 512).

Query-Parameter

  • size — Pixel-Größe, 64-2048, Default 512

Beispiel

curl https://spurig.com/api/v1/qr-codes/{id}/png?size=1024 \
  -H "Authorization: Bearer spr_live_..." \
  -o qr.png
GET/api/v1/links

Liste aller Kurzlinks.

Query-Parameter

  • campaign_id — Optionaler Kampagnen-Filter
  • archived — true|false zum Filtern
  • page / per_page — Pagination
POST/api/v1/links

Neuen Kurzlink anlegen.

Request-Body

{
  "target_url": "https://example.com/long/path",
  "title": "Newsletter Mai",
  "utm_source": "email",
  "campaign_id": "<optional>"
}
PATCH/api/v1/links/{id}

Kurzlink aktualisieren.

DELETE/api/v1/links/{id}

Kurzlink löschen.

GET/api/v1/analytics

Aggregierte Analytics. Liefert KPIs, Zeitreihe, Top-Länder, Top-Geräte.

Query-Parameter

  • from — ISO-Date (YYYY-MM-DD), Default = heute - 30 Tage
  • to — ISO-Date, Default = heute
  • campaign_id — Optionaler Kampagnen-Filter
  • source — "qr" | "link" | "all" (Default all)

Beispiel

curl "https://spurig.com/api/v1/analytics?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer spr_live_..."