バッジ API リファレンス：バッジの作成・検証・取得

バッジテンプレート、つまり受領者に発行するクレデンシャルを管理します。

CSV アップロードで、API を使わずにこのバッジを多数の受領者へ一括発行するには、一括クレデンシャルをご覧ください。

すべてのエンドポイントで、X-Api-Key ヘッダーによる認証が必要です。認証をご覧ください。

バッジを作成

検証済みの発行者の下に新しいバッジを作成します。

POST /badges

パラメータ

パラメータ	型	必須	説明
`name`	string	はい	バッジのタイトル
`description`	string	はい	バッジが表す内容
`criteria`	string	はい	受領者がこのバッジを獲得するために行ったこと
`image`	string	はい	Base64 エンコードされた画像（PNG または JPG）
`issuerId`	string	はい	検証済み発行者の ID
`shareText`	string	いいえ	このバッジのデフォルトのソーシャル共有テキスト。、、のプレースホルダーを使用できます。省略した場合は組み込みのデフォルトが使われます。
`designJson`	string	いいえ	シリアライズされたバッジデザイナーのドキュメント。後でバッジをレイヤー単位で再編集できるように保存されます。

例

bash

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

レスポンス

json

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

注意事項

バッジを作成する前に、発行者を検証しておく必要があります。
画像は Amazon S3 に保存され、変更不可でコンテンツアドレス指定の URL でグローバル CDN から配信されます。
バッジクラスを作成したら、クレデンシャル API を使って受領者に発行します。

バッジの一覧

作成したすべてのバッジを取得します。

GET /badges

例

bash

curl -X GET https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス

json

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

バッジを取得

共有テキストとシリアライズされたバッジデザイナーのドキュメント（designJson）を含め、単一のバッジを取得します。これは、バッジ編集モーダルが個々のレイヤーを復元するために使用するエンドポイントです。一覧エンドポイントでは、レスポンスを軽量に保つため designJson を省略しています。

GET /badges/{badgeId}

パラメータ

パラメータ	型	必須	説明
`badgeId`	string	はい	バッジ ID（パスパラメータ）

例

bash

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス

json

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

共有テキストは常に含まれます。より軽量な一覧版の GET /badges?badgeId={id} は、designJson を除いた同じドキュメントを返し、includeShareText=true を付けて呼び出した場合にのみ共有テキストを含めます。

バッジを更新

既存のバッジを更新します。指定したフィールドのみが変更されます。

PUT /badges/{badgeId}

パラメータ

パラメータ	型	必須	説明
`badgeId`	string	はい	バッジ ID（パスパラメータ）
`name`	string	いいえ	新しいバッジのタイトル
`description`	string	いいえ	新しい説明
`criteria`	string	いいえ	新しい基準
`image`	string	いいえ	新しい Base64 エンコード画像
`designJson`	string	いいえ	新しいシリアライズ済みバッジデザイナーのドキュメント。

例

bash

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

レスポンス

json

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

共有テキストを更新

受領者がこのバッジをソーシャルメディアで共有するときに表示されるカスタムテキストを設定します。

PUT /badges/{badgeId}/share-text

パラメータ

パラメータ	型	必須	説明
`badgeId`	string	はい	バッジ ID（パスパラメータ）
`text`	string	はい	共有テキスト（HTML は使用不可）

例

bash

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

レスポンス

json

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

バッジを削除

バッジを削除します。バッジにクレデンシャルが存在しない必要があります。

DELETE /badges/{badgeId}

例

bash

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス

単純な確認用の文字列を返します。

json

"badge has been deleted"

エラー

400 — バッジにまだ発行済みのクレデンシャルがあります："This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
404 — バッジが見つかりません

バッジ API リファレンス：バッジの作成・検証・取得 ​

バッジを作成 ​

パラメータ ​

例 ​

レスポンス ​

注意事項 ​

バッジの一覧 ​

例 ​

レスポンス ​

バッジを取得 ​

パラメータ ​

例 ​

レスポンス ​

バッジを更新 ​

パラメータ ​

例 ​

レスポンス ​

共有テキストを更新 ​

パラメータ ​

例 ​

レスポンス ​

バッジを削除 ​

例 ​

レスポンス ​

エラー ​

バッジ API リファレンス：バッジの作成・検証・取得

バッジを作成

パラメータ

例

レスポンス

注意事項

バッジの一覧

例

レスポンス

バッジを取得

パラメータ

例

レスポンス

バッジを更新

パラメータ

例

レスポンス

共有テキストを更新

パラメータ

例

レスポンス

バッジを削除

例

レスポンス

エラー