Badges API-reference: Opret, verificér og hent badges

Administrér badge-skabeloner — de beviser, du udsteder til modtagere.

Hvis du vil udstede dette badge til mange modtagere på én gang via CSV-upload i stedet for API'et, se Bulk-beviser.

Alle endpoints kræver autentificering via headeren X-Api-Key. Se Autentificering.

Opret badge

Opret et nyt badge under en verificeret udsteder.

POST /badges

Parametre

Parameter	Type	Påkrævet	Beskrivelse
name	string	Ja	Badgets titel
description	string	Ja	Hvad badget repræsenterer
criteria	string	Ja	Hvad modtageren gjorde for at optjene dette badge
image	string	Ja	Base64-kodet billede (PNG eller JPG)
issuerId	string	Ja	ID'et på den verificerede udsteder
shareText	string	Nej	Standardtekst til deling af dette badge på sociale medier. Understøtter pladsholderne , og . Falder tilbage til en indbygget standard, hvis den udelades.
designJson	string	Nej	Serialiseret badge-designer-dokument, gemt så badget senere kan redigeres lag for lag.

Eksempel

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

Noter

• Udstederen skal være verificeret, før du kan oprette badges.
• Billedet gemmes på Amazon S3 og leveres via vores globale CDN under en uforanderlig, indholdsadresseret URL.
• Når en badge-klasse findes, kan du udstede den til modtagere via Bevis-API'et.

---

List badges

Hent alle de badges, du har oprettet.

GET /badges

Eksempel

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

---

Hent badge

Hent et enkelt badge, inklusive dets delingstekst og det serialiserede badge-designer-dokument (designJson). Det er dette endpoint, som dialogen Rediger badge bruger til at genskabe de enkelte lag; liste-endpointet udelader designJson for at holde svarene slanke.

GET /badges/{badgeId}

Parametre

Parameter	Type	Påkrævet	Beskrivelse
badgeId	string	Ja	Badge-ID'et (stiparameter)

Eksempel

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

Delingsteksten er altid med. Den lettere listevariant GET /badges?badgeId={id} returnerer det samme dokument uden designJson og inkluderer kun delingsteksten, når den kaldes med includeShareText=true.

---

Opdater badge

Opdater et eksisterende badge. Kun de felter, du angiver, ændres.

PUT /badges/{badgeId}

Parametre

Parameter	Type	Påkrævet	Beskrivelse
badgeId	string	Ja	Badge-ID'et (stiparameter)
name	string	Nej	Ny badge-titel
description	string	Nej	Ny beskrivelse
criteria	string	Nej	Nye kriterier
image	string	Nej	Nyt Base64-kodet billede
designJson	string	Nej	Nyt serialiseret badge-designer-dokument.

Eksempel

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
}

---

Opdater delingstekst

Angiv den tilpassede tekst, der vises, når modtagere deler dette badge på sociale medier.

PUT /badges/{badgeId}/share-text

Parametre

Parameter	Type	Påkrævet	Beskrivelse
badgeId	string	Ja	Badge-ID'et (stiparameter)
text	string	Ja	Delingstekst (HTML er ikke tilladt)

Eksempel

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

---

Slet badge

Slet et badge. Badget må ikke have nogen beviser.

DELETE /badges/{badgeId}

Eksempel

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

Svar

Returnerer en ren bekræftelsesstreng:

"badge has been deleted"

Fejl

• 400 — badget har stadig udstedte beviser: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — badget blev ikke fundet