API-referens för märken: skapa, verifiera och hämta märken

Hantera märkesmallar — de credentials du utfärdar till mottagare.

Om du vill utfärda det här märket till många mottagare samtidigt via CSV-uppladdning i stället för via API:et, se Massutfärdade credentials.

Alla slutpunkter kräver autentisering via headern X-Api-Key. Se Autentisering.

Skapa märke

Skapa ett nytt märke under en verifierad utfärdare.

POST /badges

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
name	string	Ja	Märkets titel
description	string	Ja	Vad märket representerar
criteria	string	Ja	Vad mottagaren gjorde för att förtjäna märket
image	string	Ja	Base64-kodad bild (PNG eller JPG)
issuerId	string	Ja	ID för den verifierade utfärdaren
shareText	string	Nej	Standardtext för social delning av det här märket. Stöder platshållarna , och . Faller tillbaka på en inbyggd standardtext om den utelämnas.
designJson	string	Nej	Serialiserat dokument från märkesdesignern, sparat så att märket senare kan redigeras lager för lager.

Exempel

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

Svar

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

Anmärkningar

• Utfärdaren måste vara verifierad innan märken kan skapas.
• Bilden lagras på Amazon S3 och levereras via vårt globala CDN under en oföränderlig, innehållsadresserad URL.
• När en märkesklass finns kan du utfärda den till mottagare med Credentials API.

---

Lista märken

Hämta alla märken du har skapat.

GET /badges

Exempel

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

Svar

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

---

Hämta märke

Hämta ett enskilt märke, inklusive dess delningstext och det serialiserade dokumentet från märkesdesignern (designJson). Det är den här slutpunkten som modalen Redigera märke använder för att återskapa enskilda lager; listslutpunkten utelämnar designJson för att hålla svaren lätta.

GET /badges/{badgeId}

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
badgeId	string	Ja	Märkets ID (sökvägsparameter)

Exempel

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

Svar

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

Delningstexten ingår alltid. Den lättare listvarianten GET /badges?badgeId={id} returnerar samma dokument utan designJson, och tar bara med delningstexten när den anropas med includeShareText=true.

---

Uppdatera märke

Uppdatera ett befintligt märke. Bara de fält du anger ändras.

PUT /badges/{badgeId}

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
badgeId	string	Ja	Märkets ID (sökvägsparameter)
name	string	Nej	Ny märkestitel
description	string	Nej	Ny beskrivning
criteria	string	Nej	Nya kriterier
image	string	Nej	Ny Base64-kodad bild
designJson	string	Nej	Nytt serialiserat dokument från märkesdesignern.

Exempel

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

Svar

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

---

Uppdatera delningstext

Ange den anpassade text som visas när mottagare delar det här märket i sociala medier.

PUT /badges/{badgeId}/share-text

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
badgeId	string	Ja	Märkets ID (sökvägsparameter)
text	string	Ja	Delningstext (ingen HTML tillåten)

Exempel

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

Svar

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

---

Ta bort märke

Ta bort ett märke. Märket får inte ha några credentials.

DELETE /badges/{badgeId}

Exempel

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

Svar

Returnerar en enkel bekräftelsesträng:

"badge has been deleted"

Fel

• 400 — märket har fortfarande utfärdade credentials: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — märket hittades inte