Auszeichnungs-API

Verwalte Auszeichnungsvorlagen — die Nachweise, die du Empfänger:innen verleihst.

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

Auszeichnung erstellen

Erstellt eine neue Auszeichnung unter einem verifizierten Aussteller.

POST /badges

Parameter

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Titel der Auszeichnung
description	string	Ja	Wofür die Auszeichnung steht
criteria	string	Ja	Was der Empfänger getan hat, um sie zu erhalten
image	string	Ja	Base64-kodiertes Bild (PNG oder JPG)
issuerId	string	Ja	Die ID des verifizierten Ausstellers

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

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

Hinweise

• Der Aussteller muss verifiziert sein, bevor du Auszeichnungen erstellen kannst.
• Das Bild wird zur dauerhaften Speicherung auf IPFS hochgeladen.

---

Auszeichnungen auflisten

Ruft alle von dir erstellten Auszeichnungen ab.

GET /badges

Beispiel

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

Antwort

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

---

Auszeichnung aktualisieren

Aktualisiert eine bestehende Auszeichnung. Nur die angegebenen Felder werden geändert.

PUT /badges/{badgeId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die Auszeichnungs-ID (Pfadparameter)
name	string	Nein	Neuer Titel
description	string	Nein	Neue Beschreibung
criteria	string	Nein	Neue Kriterien
image	string	Nein	Neues Base64-kodiertes Bild

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

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

---

Share-Text aktualisieren

Lege den eigenen Text fest, der Empfänger:innen beim Teilen dieser Auszeichnung in sozialen Netzwerken angezeigt wird.

PUT /badges/{badgeId}/share-text

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die Auszeichnungs-ID (Pfadparameter)
text	string	Ja	Share-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

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

---

Auszeichnung löschen

Löscht eine Auszeichnung. Die Auszeichnung darf keine Vergaben haben.

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

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

Fehler

• 400 — die Auszeichnung hat Vergaben und kann nicht gelöscht werden
• 404 — Auszeichnung nicht gefunden