Mosaqo API voor ontwikkelaars

Een REST-API op dezelfde werkruimte die je in de app gebruikt. Alles hieronder werkt met één API-sleutel en een willekeurige HTTP-client.

Wat je kunt doen

QR-codes maken vanuit je eigen records — één voor één, of tienduizend uit een CSV.
De bestemming van een gedrukte code wijzigen, in één aanroep en zonder iets opnieuw te drukken.
De afgewerkte kaart als PNG, SVG of PDF downloaden en aan een CRM-record hangen.
Scans en geaggregeerde analytics lezen, gefilterd door de privacyregels van je werkruimte.
Ondertekende webhooks ontvangen wanneer codes worden gemaakt, gepubliceerd, gewijzigd of gearchiveerd.

Snelle start

Maak een sleutel aan in Bulk & API binnen je werkruimte, vink de scopes qr:write en qr:read aan en kopieer het secret — het wordt maar één keer getoond.

Controleer de sleutel en ontdek welke werkruimte hij opent:

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

Maak een dynamische QR-code:

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" }
  }'

Publiceer hem — dat is wat de omleiding laat werken — en haal daarna de afbeelding op die je kunt drukken:

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

Maanden later, als de campagne verhuist, verleg je dezelfde gedrukte code zonder hem opnieuw te drukken:

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" }'

Authenticatie

Stuur je secret op een van beide manieren. Allebei blijven ze de hele v1 geldig.

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

Een sleutel hoort bij precies één werkruimte, dus paden hebben geen werkruimte-id nodig: /v1/public-api/qr volstaat. De oudere vorm /v1/public-api/workspaces/{workspaceId}/qr werkt nog steeds.

Scope	Geeft recht op
`qr:read`	QR-codes, mappen en sjablonen opsommen en lezen
`qr:write`	Maken, wijzigen, verleggen, publiceren, archiveren en verwijderen
`exports:read`	Gerenderde kaarten downloaden
`analytics:read`	Geaggregeerde analytics en losse scans
`bulk:write`	Bulkopdrachten aanmaken en lezen
`webhooks:write`	Webhook-abonnementen beheren

Sleutels kunnen worden ingetrokken, van een vervaldatum voorzien en beperkt tot een IP-allowlist. Wijst die allowlist een sleutel af, dan zeggen we dat expliciet in plaats van hem ongeldig te laten lijken.

Paginering

Lijsten gebruiken keyset-paginering. Geef pagination.nextCursor ongewijzigd terug: rijen herhalen zich nooit en verdwijnen nooit doordat er halverwege de synchronisatie iets is bewerkt — wat telt bij een nachtelijke sync.

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

Wil je op wijzigingen pollen in plaats van alles te doorlopen, voeg dan updatedSince=2026-08-05T00:00:00Z toe.

Fouten

Elke fout draagt een stabiele code om op te vertakken, een leesbare message en een requestId die het waard is om aan support door te geven.

{
  "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	Wat te doen
401	`invalid_api_key`	De sleutel ontbreekt, is ingetrokken of verlopen. Vraag de gebruiker opnieuw te verbinden.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	De sleutel is geldig maar mag dit niet. Opnieuw verbinden helpt niet.
404	`not_found`	Zo’n record bestaat niet in deze werkruimte.
409	`idempotency_conflict`, `idempotency_in_progress`	Een sleutel is hergebruikt met andere gegevens, of de eerste poging loopt nog.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Corrigeer de invoer. Probeer nooit ongewijzigd opnieuw.
429	`rate_limited`	Wacht het aantal seconden uit `Retry-After` af.

Rate limits

Elk antwoord draagt je huidige budget, niet alleen de antwoorden die geweigerd worden:

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

De limiet is een bescherming tegen misbruik, geen abonnement: hij impliceert geen quotum, facturatie of upgrade.

Idempotentie

Idempotency-Key is optioneel. Stuur er een — een willekeurige unieke string — en hetzelfde verzoek binnen 24 uur opnieuw proberen speelt het oorspronkelijke antwoord af in plaats van twee keer te handelen. Dezelfde sleutel met andere gegevens geeft 409. Zonder sleutel draait het verzoek gewoon, zonder bescherming tegen herhaling.

Verder

Webhooks — de gebeurteniscatalogus en hoe je een levering verifieert.
Recepten — patronen voor Make, Zapier, n8n en CRM’s.
API-referentie — elk endpoint, met een live console.