開発者向け Mosaqo API
アプリで使っているワークスペースをそのまま操作するREST APIです。以下のすべては、APIキー1つと任意のHTTPクライアントだけで動作します。
できること
- 自社のレコードからQRコードを作成します — 1件ずつでも、CSVから1万件まとめてでも。
- 印刷済みのコードのリンク先を変更します。1回の呼び出しで済み、刷り直しは不要です。
- 完成したカードをPNG、SVG、PDFでダウンロードし、CRMのレコードに添付できます。
- ワークスペースのプライバシー設定に従って、スキャンと集計アナリティクスを読み取れます。
- コードの作成、公開、変更、アーカイブ時に、署名付きWebhookを受け取れます。
クイックスタート
ワークスペース内の Bulk & API でキーを作成し、qr:write と qr:read のスコープにチェックを入れて、シークレットをコピーしてください — 表示されるのは一度だけです。
キーを確認し、どのワークスペースを開くキーなのかを調べます。
curl https://api.mosaqo.app/v1/public-api/me \
-H "Authorization: Bearer $MOSAQO_KEY"動的QRコードを作成します。
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" }
}'公開するとリダイレクトが有効になります。続けて印刷用の画像を取得します。
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数か月後にキャンペーンが変わったら、印刷済みのコードを刷り直さずにリンク先を変更します。
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" }'認証
シークレットはどちらの方法で送っても構いません。v1では両方をサポートし続けます。
Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxxキーは必ず1つのワークスペースに属するため、パスにワークスペースIDは不要です。/v1/public-api/qr で足ります。従来の /v1/public-api/workspaces/{workspaceId}/qr という形式も引き続き使えます。
| スコープ | 許可される操作 |
|---|---|
qr:read | QRコード、フォルダ、テンプレートの一覧取得と読み取り |
qr:write | 作成、更新、リンク先変更、公開、アーカイブ、削除 |
exports:read | レンダリング済みカードのダウンロード |
analytics:read | 集計アナリティクスと個々のスキャン |
bulk:write | 一括ジョブの作成と読み取り |
webhooks:write | Webhookサブスクリプションの管理 |
キーは失効させたり、有効期限を設定したり、IP許可リストで制限したりできます。許可リストで拒否されたキーには、無効なキーに見せるのではなく、その旨を明示して返します。
ページネーション
一覧はキーセットページネーションを使います。pagination.nextCursor をそのまま渡し直してください。同期の途中で編集が入っても行が重複したり消えたりすることはなく、これは夜間同期で効いてきます。
curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
-H "Authorization: Bearer $MOSAQO_KEY"全件を辿るのではなく変更をポーリングしたい場合は、updatedSince=2026-08-05T00:00:00Z を付けてください。
エラー
どの失敗にも、分岐に使える安定した code、人が読める message、サポートに伝える価値のある requestId が含まれます。
{
"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"
}| ステータス | コード | 対処 |
|---|---|---|
| 401 | invalid_api_key | キーが未指定、失効済み、または期限切れです。ユーザーに再接続を促してください。 |
| 403 | insufficient_scope, ip_not_allowed, workspace_mismatch, quota_exceeded | キーは有効ですが、この操作は許可されていません。再接続しても解決しません。 |
| 404 | not_found | このワークスペースに該当するレコードがありません。 |
| 409 | idempotency_conflict, idempotency_in_progress | 同じキーを別の入力で再利用したか、最初の試行がまだ実行中です。 |
| 422 | validation_failed, invalid_cursor, approval_required, contrast_check_failed | 入力を修正してください。変更せずに再試行してはいけません。 |
| 429 | rate_limited | Retry-After の秒数だけ待ってください。 |
レート制限
拒否されたレスポンスだけでなく、すべてのレスポンスに現在の残量が含まれます。
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718この制限は不正利用対策であり、プランではありません。割り当て量、課金、アップグレードとは無関係です。
冪等性
Idempotency-Key は任意です。任意の一意な文字列を送っておくと、24時間以内に同一のリクエストを再送した場合、二重に実行される代わりに最初のレスポンスが再生されます。同じキーを別の入力で使い回すと 409 が返ります。キーがなければリクエストはそのまま実行され、再送保護はありません。