Badges-API

Beheer badge-sjablonen — de referenties die je aan ontvangers uitreikt.

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

Badge aanmaken

Maak een nieuwe badge aan onder een geverifieerde uitgever.

POST /badges

Parameters

Parameter	Type	Verplicht	Omschrijving
name	string	Ja	Titel van de badge
description	string	Ja	Waar de badge voor staat
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	Het ID van de geverifieerde uitgever

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

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

Opmerkingen

• De uitgever moet geverifieerd zijn voordat je badges kunt aanmaken.
• De afbeelding wordt naar IPFS geüpload voor permanente opslag.

---

Badges opvragen

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

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

---

Badge bijwerken

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

PUT /badges/{badgeId}

Parameters

Parameter	Type	Verplicht	Omschrijving
badgeId	string	Ja	Badge-ID (path-parameter)
name	string	Nee	Nieuwe titel
description	string	Nee	Nieuwe beschrijving
criteria	string	Nee	Nieuwe criteria
image	string	Nee	Nieuwe base64-gecodeerde afbeelding

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

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

---

Deeltekst bijwerken

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

PUT /badges/{badgeId}/share-text

Parameters

Parameter	Type	Verplicht	Omschrijving
badgeId	string	Ja	Badge-ID (path-parameter)
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

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

---

Badge verwijderen

Verwijder een badge. De badge mag geen uitreikingen 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

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

Fouten

• 400 — badge heeft uitreikingen en kan niet worden verwijderd
• 404 — badge niet gevonden