Badges API

Manage badge templates — the credentials you award to recipients.

All endpoints require authentication via the X-Api-Key header. See Authentication.

Create Badge

Create a new badge under a verified issuer.

POST /badges

Parameters

Parameter	Type	Required	Description
name	string	Yes	Badge title
description	string	Yes	What the badge represents
criteria	string	Yes	What the recipient did to earn this badge
image	string	Yes	Base64-encoded image (PNG or JPG)
issuerId	string	Yes	The ID of the verified issuer

Example

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

Response

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

Notes

• The issuer must be verified before creating badges.
• The image is uploaded to IPFS for permanent storage.

---

List Badges

Retrieve all badges you have created.

GET /badges

Example

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

Response

{
  "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"
      }
    ]
  }
}

---

Update Badge

Update an existing badge. Only the fields you provide are changed.

PUT /badges/{badgeId}

Parameters

Parameter	Type	Required	Description
badgeId	string	Yes	The badge ID (path parameter)
name	string	No	New badge title
description	string	No	New description
criteria	string	No	New criteria
image	string	No	New base64-encoded image

Example

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

Response

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

---

Update Share Text

Set the custom text displayed when recipients share this badge on social media.

PUT /badges/{badgeId}/share-text

Parameters

Parameter	Type	Required	Description
badgeId	string	Yes	The badge ID (path parameter)
text	string	Yes	Share text (no HTML allowed)

Example

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

Response

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

---

Delete Badge

Delete a badge. The badge must have no awards.

DELETE /badges/{badgeId}

Example

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

Response

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

Errors

• 400 — badge has awards and cannot be deleted
• 404 — badge not found