Badges API-referentie: badges aanmaken, verifiëren en ophalen

Beheer badgesjablonen — de credentials die je aan ontvangers uitgeeft.

Wil je deze badge via een CSV-upload aan veel ontvangers tegelijk uitgeven in plaats van via de API? Zie dan Bulk-credentials.

Alle endpoints vereisen authenticatie via de X-Api-Key-header. Zie Authenticatie.

Create Badge

Maak een nieuwe badge aan onder een geverifieerde uitgever.

POST /badges

Parameters

Parameter	Type	Verplicht	Beschrijving
name	string	Ja	Titel van de badge
description	string	Ja	Wat de badge vertegenwoordigt
criteria	string	Ja	Wat de ontvanger heeft gedaan om deze badge te verdienen
image	string	Ja	Base64-gecodeerde afbeelding (PNG of JPG)
issuerId	string	Ja	De ID van de geverifieerde uitgever
shareText	string	Nee	Standaard deeltekst voor sociale media voor deze badge. Ondersteunt de placeholders , en . Valt terug op een ingebouwde standaardtekst als deze wordt weggelaten.
designJson	string	Nee	Geserialiseerd document van de badge-designer, opgeslagen zodat de badge later laag voor laag opnieuw kan worden bewerkt.

Voorbeeld

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

Respons

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

Opmerkingen

• De uitgever moet zijn geverifieerd voordat je badges kunt aanmaken.
• De afbeelding wordt opgeslagen op Amazon S3 en geleverd via ons wereldwijde CDN onder een onveranderlijke, op inhoud gebaseerde URL.
• Zodra een badgeklasse bestaat, geef je die uit aan ontvangers via de Credentials-API.

---

List Badges

Haal alle badges op die je hebt aangemaakt.

GET /badges

Voorbeeld

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

Respons

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

Haal één badge op, inclusief de deeltekst en het geserialiseerde document van de badge-designer (designJson). Dit is het endpoint dat de Edit Badge-modal gebruikt om afzonderlijke lagen te herstellen; het lijst-endpoint laat designJson weg om responses compact te houden.

GET /badges/{badgeId}

Parameters

Parameter	Type	Verplicht	Beschrijving
badgeId	string	Ja	De badge-ID (padparameter)

Voorbeeld

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

Respons

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

De deeltekst wordt altijd meegestuurd. De lichtere lijstvariant GET /badges?badgeId={id} geeft hetzelfde document terug zonder designJson en neemt de deeltekst alleen op wanneer deze wordt aangeroepen met includeShareText=true.

---

Update Badge

Werk een bestaande badge bij. Alleen de velden die je opgeeft, worden gewijzigd.

PUT /badges/{badgeId}

Parameters

Parameter	Type	Verplicht	Beschrijving
badgeId	string	Ja	De badge-ID (padparameter)
name	string	Nee	Nieuwe titel van de badge
description	string	Nee	Nieuwe beschrijving
criteria	string	Nee	Nieuwe criteria
image	string	Nee	Nieuwe base64-gecodeerde afbeelding
designJson	string	Nee	Nieuw geserialiseerd document van de badge-designer.

Voorbeeld

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

Respons

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

---

Update Share Text

Stel de aangepaste tekst in die wordt getoond wanneer ontvangers deze badge op sociale media delen.

PUT /badges/{badgeId}/share-text

Parameters

Parameter	Type	Verplicht	Beschrijving
badgeId	string	Ja	De badge-ID (padparameter)
text	string	Ja	Deeltekst (geen HTML toegestaan)

Voorbeeld

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

Respons

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

---

Delete Badge

Verwijder een badge. De badge mag geen credentials hebben.

DELETE /badges/{badgeId}

Voorbeeld

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

Respons

Geeft een eenvoudige bevestigingsstring terug:

"badge has been deleted"

Fouten

• 400 — de badge heeft nog uitgegeven 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 niet gevonden