Badges API Reference: Gumawa, Mag-verify at Kumuha ng mga Badge

Pamahalaan ang mga badge template — ang mga credential na ini-issue mo sa mga recipient.

Para mag-issue ng badge na ito sa maraming recipient nang sabay-sabay sa pamamagitan ng CSV upload sa halip na API, tingnan ang Bulk Credentials.

Lahat ng endpoint ay nangangailangan ng authentication sa pamamagitan ng X-Api-Key header. Tingnan ang Authentication.

Gumawa ng Badge

Gumawa ng bagong badge sa ilalim ng isang na-verify na issuer.

POST /badges

Mga Parameter

Parameter	Uri	Kinakailangan	Paglalarawan
name	string	Oo	Pamagat ng badge
description	string	Oo	Ang ipinapahiwatig ng badge
criteria	string	Oo	Ang ginawa ng recipient para makuha ang badge na ito
image	string	Oo	Base64-encoded na imahe (PNG o JPG)
issuerId	string	Oo	Ang ID ng na-verify na issuer
shareText	string	Hindi	Default na social-share text para sa badge na ito. Sinusuportahan ang mga placeholder na , , at . Gagamit ng built-in na default kung hindi ibinigay.
designJson	string	Hindi	Naka-serialize na badge-designer document, iniimbak para mai-edit muli ang badge nang layer-by-layer sa susunod.

Halimbawa

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

Mga Tala

• Dapat na-verify ang issuer bago gumawa ng mga badge.
• Iniimbak ang imahe sa Amazon S3 at inihahatid sa pamamagitan ng global CDN namin sa ilalim ng immutable, content-addressed na URL.
• Kapag may badge class na, i-issue ito sa mga recipient gamit ang Credentials API.

---

Ilista ang mga Badge

Kunin ang lahat ng badge na ginawa mo.

GET /badges

Halimbawa

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

---

Kunin ang Badge

Kunin ang isang badge, kasama ang share text nito at ang naka-serialize na badge-designer document (designJson). Ito ang endpoint na ginagamit ng Edit Badge modal para i-rehydrate ang bawat layer; hindi isinasama ng list endpoint ang designJson para manatiling magaan ang mga response.

GET /badges/{badgeId}

Mga Parameter

Parameter	Uri	Kinakailangan	Paglalarawan
badgeId	string	Oo	Ang badge ID (path parameter)

Halimbawa

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

Palaging kasama ang share text. Ang mas magaang GET /badges?badgeId={id} na list variant ay nagbabalik ng parehong document nang walang designJson, at isinasama lang ang share text kapag tinawag nang may includeShareText=true.

---

I-update ang Badge

I-update ang umiiral na badge. Ang mga field lang na ibinigay mo ang mababago.

PUT /badges/{badgeId}

Mga Parameter

Parameter	Uri	Kinakailangan	Paglalarawan
badgeId	string	Oo	Ang badge ID (path parameter)
name	string	Hindi	Bagong pamagat ng badge
description	string	Hindi	Bagong paglalarawan
criteria	string	Hindi	Bagong criteria
image	string	Hindi	Bagong base64-encoded na imahe
designJson	string	Hindi	Bagong naka-serialize na badge-designer document.

Halimbawa

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
}

---

I-update ang Share Text

I-set ang custom na text na ipinapakita kapag ibinahagi ng mga recipient ang badge na ito sa social media.

PUT /badges/{badgeId}/share-text

Mga Parameter

Parameter	Uri	Kinakailangan	Paglalarawan
badgeId	string	Oo	Ang badge ID (path parameter)
text	string	Oo	Share text (bawal ang HTML)

Halimbawa

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

---

Tanggalin ang Badge

Tanggalin ang isang badge. Dapat walang credential ang badge.

DELETE /badges/{badgeId}

Halimbawa

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

Response

Nagbabalik ng simpleng confirmation string:

"badge has been deleted"

Mga Error

• 400 — may mga na-issue pang credential ang badge: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — hindi nahanap ang badge