배지 API

배지 템플릿 — 수령자에게 수여하는 자격을 관리합니다.

모든 엔드포인트는 X-Api-Key 헤더를 통한 인증이 필요합니다. 인증 을 참고하세요.

배지 생성

검증된 발급자 아래에 새 배지를 생성합니다.

POST /badges

파라미터

파라미터	타입	필수	설명
name	string	예	배지 제목
description	string	예	배지가 의미하는 바
criteria	string	예	수령자가 이 배지를 얻기 위해 한 일
image	string	예	Base64 인코딩 이미지(PNG 또는 JPG)
issuerId	string	예	검증된 발급자의 ID

예시

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

응답

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

참고

• 배지를 만들기 전에 발급자가 검증되어 있어야 합니다.
• 이미지는 영구 보존을 위해 IPFS에 업로드됩니다.

---

배지 목록

생성한 모든 배지를 가져옵니다.

GET /badges

예시

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

응답

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

---

배지 업데이트

기존 배지를 업데이트합니다. 제공한 필드만 변경됩니다.

PUT /badges/{badgeId}

파라미터

파라미터	타입	필수	설명
badgeId	string	예	배지 ID(경로 파라미터)
name	string	아니요	새 배지 제목
description	string	아니요	새 설명
criteria	string	아니요	새 기준
image	string	아니요	새 Base64 인코딩 이미지

예시

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

응답

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

---

공유 문구 업데이트

수령자가 이 배지를 소셜 미디어에서 공유할 때 표시될 사용자 지정 문구를 설정합니다.

PUT /badges/{badgeId}/share-text

파라미터

파라미터	타입	필수	설명
badgeId	string	예	배지 ID(경로 파라미터)
text	string	예	공유 문구(HTML 불가)

예시

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

응답

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

---

배지 삭제

배지를 삭제합니다. 배지에 수여가 하나도 없어야 합니다.

DELETE /badges/{badgeId}

예시

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

응답

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

오류

• 400 — 배지에 수여가 있어 삭제할 수 없습니다
• 404 — 배지를 찾을 수 없음