Mosaqo API für Entwickler

Eine REST-API auf denselben Workspace, den Sie in der App nutzen. Alles Folgende funktioniert mit einem einzigen API-Schlüssel und einem beliebigen HTTP-Client.

Was möglich ist

QR-Codes aus Ihren eigenen Datensätzen erstellen — einzeln oder zehntausend aus einer CSV.
Das Ziel eines gedruckten Codes ändern, mit einem Aufruf und ohne Nachdruck.
Die fertige Karte als PNG, SVG oder PDF laden und an einen CRM-Datensatz hängen.
Scans und aggregierte Analytics lesen, gefiltert nach den Datenschutzregeln Ihres Workspace.
Signierte Webhooks erhalten, wenn Codes erstellt, veröffentlicht, geändert oder archiviert werden.

Schnellstart

Erstellen Sie in Ihrem Workspace unter Bulk & API einen Schlüssel, setzen Sie die Scopes qr:write und qr:read und kopieren Sie das Secret — es wird nur einmal angezeigt.

Prüfen Sie den Schlüssel und finden Sie heraus, welchen Workspace er öffnet:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

Einen dynamischen QR-Code erstellen:

curl -X POST https://api.mosaqo.app/v1/public-api/qr \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn campaign",
    "mode": "dynamic",
    "contentType": "url",
    "content": { "targetUrl": "https://example.com/autumn" }
  }'

Veröffentlichen Sie ihn — erst das lässt die Weiterleitung greifen — und holen Sie dann das druckbare Bild:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
  -H "Authorization: Bearer $MOSAQO_KEY"

curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
  -H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png

Monate später, wenn die Kampagne umzieht, lenken Sie denselben gedruckten Code um, ohne ihn neu zu drucken:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/winter" }'

Authentifizierung

Senden Sie Ihr Secret auf einem der beiden Wege. Beide gelten für die gesamte v1.

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

Ein Schlüssel gehört zu genau einem Workspace, deshalb brauchen Pfade keine Workspace-ID: /v1/public-api/qr genügt. Die ältere Form /v1/public-api/workspaces/{workspaceId}/qr funktioniert weiterhin.

Scope	Erlaubt
`qr:read`	QR-Codes, Ordner und Vorlagen auflisten und lesen
`qr:write`	Erstellen, ändern, umlenken, veröffentlichen, archivieren und löschen
`exports:read`	Gerenderte Karten herunterladen
`analytics:read`	Aggregierte Analytics und einzelne Scans
`bulk:write`	Bulk-Jobs anlegen und lesen
`webhooks:write`	Webhook-Abonnements verwalten

Schlüssel lassen sich widerrufen, mit einem Ablaufdatum versehen und auf eine IP-Allowlist beschränken. Wird ein Schlüssel von der Allowlist abgewiesen, sagen wir das ausdrücklich, statt ihn ungültig aussehen zu lassen.

Paginierung

Listen nutzen Keyset-Paginierung. Geben Sie pagination.nextCursor unverändert zurück; Zeilen wiederholen sich nie und verschwinden nie, weil mitten im Abgleich etwas bearbeitet wurde — was für einen nächtlichen Sync entscheidend ist.

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Um auf Änderungen zu pollen, statt alles zu durchlaufen, ergänzen Sie updatedSince=2026-08-05T00:00:00Z.

Fehler

Jeder Fehler trägt einen stabilen code zum Verzweigen, eine lesbare message und eine requestId, die im Supportfall zu nennen ist.

{
  "error": "This API key does not have the qr:write scope.",
  "message": "This API key does not have the qr:write scope.",
  "code": "insufficient_scope",
  "details": { "required": "qr:write", "granted": ["qr:read"] },
  "requestId": "req-42"
}

Status	Codes	Was zu tun ist
401	`invalid_api_key`	Der Schlüssel fehlt, wurde widerrufen oder ist abgelaufen. Bitten Sie die Person, sich neu zu verbinden.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	Der Schlüssel ist gültig, darf das aber nicht. Neu verbinden hilft nicht.
404	`not_found`	Kein solcher Datensatz in diesem Workspace.
409	`idempotency_conflict`, `idempotency_in_progress`	Ein Schlüssel wurde mit anderen Daten wiederverwendet, oder der erste Versuch läuft noch.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Korrigieren Sie die Eingabe. Niemals unverändert wiederholen.
429	`rate_limited`	Warten Sie die Sekunden aus `Retry-After` ab.

Rate Limits

Jede Antwort trägt Ihr aktuelles Budget, nicht nur die abgelehnten:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

Das Limit ist ein Missbrauchsschutz, kein Tarif: Es bedeutet weder Kontingent noch Abrechnung noch ein Upgrade.

Idempotenz

Idempotency-Key ist optional. Senden Sie einen — irgendeine eindeutige Zeichenfolge — und ein identischer Wiederholungsversuch innerhalb von 24 Stunden gibt die ursprüngliche Antwort zurück, statt zweimal zu handeln. Derselbe Schlüssel mit anderen Daten ergibt 409. Ohne Schlüssel läuft die Anfrage einfach, ohne Schutz vor Wiederholung.

Weiter

Webhooks — der Ereigniskatalog und wie man eine Zustellung prüft.
Rezepte — Muster für Make, Zapier, n8n und CRMs.
API-Referenz — jeder Endpunkt, mit Live-Konsole.