Référence de l'API Badges : créer, vérifier et récupérer des badges

Gérez les modèles de badge — les crédentiels que vous délivrez à vos destinataires.

Pour délivrer ce badge à de nombreux destinataires à la fois par import CSV plutôt que via l'API, consultez Crédentiels en masse.

Tous les points de terminaison nécessitent une authentification via l'en-tête X-Api-Key. Voir Authentification.

Créer un badge

Créez un nouveau badge sous un émetteur vérifié.

POST /badges

Paramètres

Paramètre	Type	Obligatoire	Description
name	string	Oui	Titre du badge
description	string	Oui	Ce que représente le badge
criteria	string	Oui	Ce que le destinataire a accompli pour obtenir ce badge
image	string	Oui	Image encodée en Base64 (PNG ou JPG)
issuerId	string	Oui	L'ID de l'émetteur vérifié
shareText	string	Non	Texte de partage social par défaut pour ce badge. Prend en charge les espaces réservés , et . Si omis, un texte par défaut intégré est utilisé.
designJson	string	Non	Document sérialisé du concepteur de badge, conservé afin de pouvoir modifier le badge couche par couche ultérieurement.

Exemple

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

Réponse

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

Remarques

• L'émetteur doit être vérifié avant de pouvoir créer des badges.
• L'image est stockée sur Amazon S3 et servie via notre CDN mondial sous une URL immuable adressée par son contenu.
• Une fois la classe de badge créée, délivrez-la à vos destinataires avec l'API Crédentiels.

---

Lister les badges

Récupérez tous les badges que vous avez créés.

GET /badges

Exemple

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

Réponse

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

---

Obtenir un badge

Récupérez un seul badge, avec son texte de partage et le document sérialisé du concepteur de badge (designJson). C'est le point de terminaison que la fenêtre de modification du badge utilise pour réhydrater chaque couche ; le point de terminaison de liste omet designJson pour alléger les réponses.

GET /badges/{badgeId}

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	L'ID du badge (paramètre de chemin)

Exemple

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

Réponse

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

Le texte de partage est toujours inclus. La variante de liste allégée GET /badges?badgeId={id} renvoie le même document sans designJson, et n'inclut le texte de partage que lorsqu'elle est appelée avec includeShareText=true.

---

Mettre à jour un badge

Mettez à jour un badge existant. Seuls les champs que vous fournissez sont modifiés.

PUT /badges/{badgeId}

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	L'ID du badge (paramètre de chemin)
name	string	Non	Nouveau titre du badge
description	string	Non	Nouvelle description
criteria	string	Non	Nouveaux critères
image	string	Non	Nouvelle image encodée en Base64
designJson	string	Non	Nouveau document sérialisé du concepteur de badge.

Exemple

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

Réponse

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

---

Mettre à jour le texte de partage

Définissez le texte personnalisé affiché lorsque les destinataires partagent ce badge sur les réseaux sociaux.

PUT /badges/{badgeId}/share-text

Paramètres

Paramètre	Type	Obligatoire	Description
badgeId	string	Oui	L'ID du badge (paramètre de chemin)
text	string	Oui	Texte de partage (HTML non autorisé)

Exemple

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

Réponse

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

---

Supprimer un badge

Supprimez un badge. Le badge ne doit avoir aucun crédentiel.

DELETE /badges/{badgeId}

Exemple

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

Réponse

Renvoie une simple chaîne de confirmation :

"badge has been deleted"

Erreurs

• 400 — le badge a encore des crédentiels délivrés : "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — badge introuvable