배지 API 레퍼런스: 배지 생성, 검증 및 조회

배지 템플릿, 즉 수령자에게 발급하는 자격 증명을 관리해요.

API 대신 CSV 업로드로 이 배지를 여러 수령자에게 한꺼번에 발급하려면 대량 자격 증명을 참조하세요.

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

배지 생성

검증된 발급자 아래에 새 배지를 생성해요.

POST /badges

파라미터

파라미터	타입	필수	설명
name	string	예	배지 제목
description	string	예	배지가 나타내는 내용
criteria	string	예	수령자가 이 배지를 받기 위해 한 일
image	string	예	Base64로 인코딩된 이미지(PNG 또는 JPG)
issuerId	string	예	검증된 발급자의 ID
shareText	string	아니요	이 배지의 기본 소셜 공유 텍스트. , , 플레이스홀더를 지원해요. 생략하면 내장 기본값이 사용돼요.
designJson	string	아니요	직렬화된 배지 디자이너 문서. 나중에 배지를 레이어별로 다시 편집할 수 있도록 저장돼요.

예시

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

응답

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

참고

• 배지를 생성하려면 먼저 발급자가 검증되어 있어야 해요.
• 이미지는 Amazon S3에 저장되며, 변경되지 않는 콘텐츠 주소 기반 URL로 글로벌 CDN을 통해 제공돼요.
• 배지 클래스가 만들어지면 자격 증명 API를 사용해 수령자에게 발급하세요.

---

배지 목록 조회

생성한 모든 배지를 조회해요.

GET /badges

예시

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

응답

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

---

배지 조회

공유 텍스트와 직렬화된 배지 디자이너 문서(designJson)를 포함해 단일 배지를 조회해요. 배지 편집 모달이 개별 레이어를 복원할 때 사용하는 엔드포인트예요. 목록 엔드포인트는 응답을 가볍게 유지하기 위해 designJson을 생략해요.

GET /badges/{badgeId}

파라미터

파라미터	타입	필수	설명
badgeId	string	예	배지 ID(경로 파라미터)

예시

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

응답

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

공유 텍스트는 항상 포함돼요. 더 가벼운 GET /badges?badgeId={id} 목록 방식은 designJson 없이 같은 문서를 반환하며, includeShareText=true로 호출할 때만 공유 텍스트를 포함해요.

---

배지 업데이트

기존 배지를 업데이트해요. 제공한 필드만 변경돼요.

PUT /badges/{badgeId}

파라미터

파라미터	타입	필수	설명
badgeId	string	예	배지 ID(경로 파라미터)
name	string	아니요	새 배지 제목
description	string	아니요	새 설명
criteria	string	아니요	새 기준
image	string	아니요	Base64로 인코딩된 새 이미지
designJson	string	아니요	직렬화된 새 배지 디자이너 문서

예시

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

응답

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

응답

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

---

배지 삭제

배지를 삭제해요. 배지에 자격 증명이 없어야 해요.

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"

응답

일반 확인 문자열을 반환해요.

"badge has been deleted"

오류

• 400 — 배지에 발급된 자격 증명이 아직 있어요: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — 배지를 찾을 수 없어요