Badges-API-Referenz: Badges erstellen, verifizieren & abrufen

Verwalte Abzeichen-Vorlagen — die Nachweise, die du an Empfänger:innen ausstellst.

Wenn du dieses Abzeichen per CSV-Upload statt über die API an viele Empfänger:innen gleichzeitig ausstellen möchtest, siehe Massennachweise.

Alle Endpunkte erfordern Authentifizierung über den X-Api-Key-Header. Siehe Authentifizierung.

Abzeichen erstellen

Erstelle ein neues Abzeichen unter einem verifizierten Aussteller.

POST /badges

Parameter

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Titel des Abzeichens
description	string	Ja	Was das Abzeichen darstellt
criteria	string	Ja	Was die empfangende Person getan hat, um dieses Abzeichen zu erhalten
image	string	Ja	Base64-kodiertes Bild (PNG oder JPG)
issuerId	string	Ja	Die ID des verifizierten Ausstellers
shareText	string	Nein	Standard-Text zum Teilen dieses Abzeichens in sozialen Netzwerken. Unterstützt die Platzhalter , und . Fällt auf einen eingebauten Standard zurück, wenn er fehlt.
designJson	string	Nein	Serialisiertes Dokument des Badge-Designers, gespeichert, damit das Abzeichen später Ebene für Ebene erneut bearbeitet werden kann.

Beispiel

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

Antwort

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

Hinweise

• Der Aussteller muss verifiziert sein, bevor du Abzeichen erstellen kannst.
• Das Bild wird auf Amazon S3 gespeichert und über unser globales CDN unter einer unveränderlichen, inhaltsadressierten URL ausgeliefert.
• Sobald eine Abzeichen-Klasse existiert, stelle sie den Empfänger:innen über die Nachweis-API aus.

---

Abzeichen auflisten

Rufe alle Abzeichen ab, die du erstellt hast.

GET /badges

Beispiel

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

Antwort

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

---

Abzeichen abrufen

Rufe ein einzelnes Abzeichen ab, einschließlich seines Teilen-Texts und des serialisierten Badge-Designer-Dokuments (designJson). Dies ist der Endpunkt, den der Dialog „Abzeichen bearbeiten“ verwendet, um einzelne Ebenen wiederherzustellen; der Listen-Endpunkt lässt designJson weg, damit die Antworten schlank bleiben.

GET /badges/{badgeId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die Abzeichen-ID (Pfadparameter)

Beispiel

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

Antwort

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

Der Teilen-Text ist immer enthalten. Die schlankere Listenvariante GET /badges?badgeId={id} gibt dasselbe Dokument ohne designJson zurück und enthält den Teilen-Text nur, wenn sie mit includeShareText=true aufgerufen wird.

---

Abzeichen aktualisieren

Aktualisiere ein bestehendes Abzeichen. Nur die Felder, die du angibst, werden geändert.

PUT /badges/{badgeId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die Abzeichen-ID (Pfadparameter)
name	string	Nein	Neuer Titel des Abzeichens
description	string	Nein	Neue Beschreibung
criteria	string	Nein	Neue Kriterien
image	string	Nein	Neues Base64-kodiertes Bild
designJson	string	Nein	Neues serialisiertes Badge-Designer-Dokument.

Beispiel

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

Antwort

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

---

Teilen-Text aktualisieren

Lege den benutzerdefinierten Text fest, der angezeigt wird, wenn Empfänger:innen dieses Abzeichen in sozialen Medien teilen.

PUT /badges/{badgeId}/share-text

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die Abzeichen-ID (Pfadparameter)
text	string	Ja	Teilen-Text (kein HTML erlaubt)

Beispiel

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

Antwort

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

---

Abzeichen löschen

Lösche ein Abzeichen. Zu dem Abzeichen dürfen keine Nachweise existieren.

DELETE /badges/{badgeId}

Beispiel

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

Antwort

Gibt eine einfache Bestätigungszeichenkette zurück:

"badge has been deleted"

Fehler

• 400 — das Abzeichen hat noch ausgestellte Nachweise: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — Abzeichen nicht gefunden