Badges API-referanse: Opprett, verifiser og hent merker

Administrer merkemaler — legitimasjonen du utsteder til mottakere.

Hvis du vil utstede dette merket til mange mottakere samtidig via CSV-opplasting i stedet for API-et, se Masselegitimasjon.

Alle endepunkter krever autentisering via X-Api-Key-headeren. Se Autentisering.

Create Badge

Opprett et nytt merke under en verifisert utsteder.

POST /badges

Parametere

Parameter	Type	Påkrevd	Beskrivelse
name	string	Ja	Merkets tittel
description	string	Ja	Hva merket representerer
criteria	string	Ja	Hva mottakeren gjorde for å oppnå dette merket
image	string	Ja	Base64-kodet bilde (PNG eller JPG)
issuerId	string	Ja	ID-en til den verifiserte utstederen
shareText	string	Nei	Standard tekst for deling på sosiale medier for dette merket. Støtter plassholderne , og . Faller tilbake til en innebygd standard hvis utelatt.
designJson	string	Nei	Serialisert dokument fra merkedesigneren, lagret slik at merket 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"
    }
  }'

Respons

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

Merknader

• Utstederen må være verifisert før du kan opprette merker.
• Bildet lagres på Amazon S3 og leveres via vårt globale CDN under en uforanderlig, innholdsadressert URL.
• Når en merkeklasse finnes, kan du utstede den til mottakere med Legitimasjons-API-et.

---

List Badges

Hent alle merkene du har opprettet.

GET /badges

Eksempel

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

Respons

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

---

Get Badge

Hent ett enkelt merke, inkludert delingsteksten og det serialiserte dokumentet fra merkedesigneren (designJson). Dette er endepunktet som Edit Badge-modalen bruker for å gjenopprette de enkelte lagene; listeendepunktet utelater designJson for å holde svarene slanke.

GET /badges/{badgeId}

Parametere

Parameter	Type	Påkrevd	Beskrivelse
badgeId	string	Ja	Merkets ID (path-parameter)

Eksempel

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

Respons

{
  "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 alltid med. Den lettere listevarianten GET /badges?badgeId={id} returnerer det samme dokumentet uten designJson, og tar bare med delingsteksten når den kalles med includeShareText=true.

---

Update Badge

Oppdater et eksisterende merke. Bare feltene du oppgir, endres.

PUT /badges/{badgeId}

Parametere

Parameter	Type	Påkrevd	Beskrivelse
badgeId	string	Ja	Merkets ID (path-parameter)
name	string	Nei	Ny tittel på merket
description	string	Nei	Ny beskrivelse
criteria	string	Nei	Nye kriterier
image	string	Nei	Nytt base64-kodet bilde
designJson	string	Nei	Nytt serialisert dokument fra merkedesigneren.

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

Respons

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

---

Update Share Text

Angi den egendefinerte teksten som vises når mottakere deler dette merket på sosiale medier.

PUT /badges/{badgeId}/share-text

Parametere

Parameter	Type	Påkrevd	Beskrivelse
badgeId	string	Ja	Merkets ID (path-parameter)
text	string	Ja	Delingstekst (HTML er ikke tillatt)

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

Respons

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

---

Delete Badge

Slett et merke. Merket kan ikke ha noen legitimasjoner.

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"

Respons

Returnerer en enkel bekreftelsesstreng:

"badge has been deleted"

Feil

• 400 — merket har fortsatt utstedt legitimasjon: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — merket ble ikke funnet