バッジ API

バッジテンプレート — 受領者に授与する資格を管理します。

すべてのエンドポイントは X-Api-Key ヘッダーでの認証が必要です。認証 を参照してください。

バッジの作成

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

POST /badges

パラメータ

パラメータ	型	必須	説明
name	string	必須	バッジのタイトル
description	string	必須	バッジが表す内容
criteria	string	必須	受領者がバッジを得るために行ったこと
image	string	必須	Base64 エンコードされた画像(PNG または JPG)
issuerId	string	必須	確認済み発行者の ID

例

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

レスポンス

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

注意

• 発行者は確認済みである必要があります。
• 画像は永続保存のために IPFS にアップロードされます。

---

バッジの一覧

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

GET /badges

例

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

レスポンス

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

バッジの更新

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

PUT /badges/{badgeId}

パラメータ

パラメータ	型	必須	説明
badgeId	string	必須	バッジ ID(パスパラメータ)
name	string	任意	新しいバッジタイトル
description	string	任意	新しい説明
criteria	string	任意	新しい基準
image	string	任意	新しい Base64 エンコード画像

例

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

レスポンス

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

---

共有テキストの更新

受領者がこのバッジを SNS で共有するときに表示されるカスタムテキストを設定します。

PUT /badges/{badgeId}/share-text

パラメータ

パラメータ	型	必須	説明
badgeId	string	必須	バッジ ID(パスパラメータ)
text	string	必須	共有テキスト(HTML 不可)

例

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

レスポンス

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

バッジの削除

バッジを削除します。バッジに授与が 1 つもないことが必要です。

DELETE /badges/{badgeId}

例

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

レスポンス

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

エラー

• 400 — バッジに授与があり、削除できません
• 404 — バッジが見つかりません