Badges API Reference: Create, Verify & Retrieve Badges

Manage badge templates — the credentials you issue to recipients.

To issue this badge to many recipients at once via CSV upload instead of the API, see Bulk Credentials.

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
shareText	string	No	Default social-share text for this badge. Supports , , and placeholders. Falls back to a built-in default if omitted.
designJson	string	No	Serialized badge-designer document, stored so the badge can be re-edited layer-by-layer later.

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

{
  "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 stored on Amazon S3 and served via our global CDN under an immutable, content-addressed URL.
• Once a badge class exists, issue it to recipients using the Credentials API.

---

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

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

---

Get Badge

Retrieve a single badge, including its share text and the serialized badge-designer document (designJson). This is the endpoint the Edit Badge modal uses to rehydrate individual layers; the list endpoint omits designJson to keep responses lean.

GET /badges/{badgeId}

Parameters

Parameter	Type	Required	Description
badgeId	string	Yes	The badge ID (path parameter)

Example

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

Response

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

The share text is always included. The lighter GET /badges?badgeId={id} list variant returns the same document without designJson, and only includes the share text when called with includeShareText=true.

---

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
designJson	string	No	New serialized badge-designer document.

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

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

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

---

Delete Badge

Delete a badge. The badge must have no credentials.

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

Returns a plain confirmation string:

"badge has been deleted"

Errors

• 400 — the badge still has issued credentials: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — badge not found