Badgeclasses | Instructure Developer Documentation Portal

Get a single BadgeClass

get

Authorizations

Path parameters

idOrEntityIdstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

400

Bad Request

*/*

get

GET /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing BadgeClass.

put

Previously awarded Assertions will be updated with image rebaking

Authorizations

Path parameters

idOrEntityIdstringRequired

Body

namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert

descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.

imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image

achievementTypestringOptional

The type of achievement

Example: Course

criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria

criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

200

OK

400

Bad Request

*/*

put

PUT /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 974

{
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a BadgeClass

delete

Restricted to owners or editors (not staff) of the corresponding Issuer.

Authorizations

Path parameters

idOrEntityIdstringRequired

Query parameters

hard_deletestringOptional

archivalNotestringOptional

Responses

204

BadgeClass deleted

400

Bad Request

*/*

delete

DELETE /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing ClaimCode for a BadgeClass

put

Authorizations

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Body

labelstringOptional

The label of the claim code

Example: Conference Event

limitinteger · int64Optional

The number of times the claim code can be used

Example: 10

expirationDatestring · date-timeOptional

Responses

200

OK

400

Bad Request

*/*

put

PUT /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2025-07-15T19:17:56.673Z"
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-15T19:17:56.673Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Archive a ClaimCode for a BadgeClass

delete

Authorizations

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

204

No Content

400

Bad Request

*/*

delete

DELETE /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeClass

get

Authorizations

Path parameters

refstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

400

Bad Request

*/*

get

GET /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing BadgeClass.

put

Previously awarded Assertions will be updated with image rebaking

Authorizations

Path parameters

refstringRequired

Body

namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert

descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.

imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image

achievementTypestringOptional

The type of achievement

Example: Course

criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria

criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

200

OK

400

Bad Request

*/*

put

PUT /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 974

{
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a BadgeClass

delete

Restricted to owners or editors (not staff) of the corresponding Issuer.

Authorizations

Path parameters

refstringRequired

Query parameters

hard_deletestringOptional

archivalNotestringOptional

Responses

204

BadgeClass deleted

400

Bad Request

*/*

delete

DELETE /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get list of Assertions for the specified scope

get

Authorizations

Path parameters

scopestring · enumRequiredPossible values:

idOrEntityIdstringRequired

Query parameters

recipientstringOptional

A recipient identifier to filter by

numinteger · int32Optional

Request pagination of results, before/after cursors may be provided in response header

include_expiredbooleanOptionalDefault: false

include_revokedbooleanOptionalDefault: false

afterstringOptional

Pagination cursor provided in "Link" response header

beforestringOptional

Pagination cursor provided in "Link" response header

Responses

200

List of Assertions

400

Bad Request

*/*

get

GET /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-15T19:17:56.673Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-15T19:17:56.673Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-15T19:17:56.673Z",
        "activityEnd": "2025-07-15T19:17:56.673Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Issue a new Assertion to a recipient

post

Authorizations

Path parameters

scopestring · enumRequiredPossible values:

idOrEntityIdstringRequired

The entity ID of the selected scope entity

Example: K829IK8RS6ercwkpeFOn-Q

Body

Request to award an assertion. When request scope is issuers, one of badgeclass or badgeclassOpenBadgeId must be provided.

badgeclassstringOptional

ID or Entity ID of the badge class to be awarded

Example: K829IK8RS6ercwkpeFOn-Q

badgeclassOpenBadgeIdstring · uriOptional

OB URL of the badge class to be awarded

Example: https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q

issuedOnstring · date-timeOptional

Timestamp when the assertion was issued

allowDuplicateAwardsbooleanOptional

If set to false and the recipient already has this assertion, then the request will fail

narrativestringOptional

Markdown narrative of the achievement

expiresstring · date-timeOptional

Responses

201

Created

400

Bad Request

*/*

post

POST /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 650

{
  "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
  "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
  "issuedOn": "2025-07-15T19:17:56.673Z",
  "recipient": {
    "identity": "[email protected]",
    "type": "email",
    "hashed": true
  },
  "allowDuplicateAwards": true,
  "narrative": "text",
  "evidence": [
    {
      "url": "https://example.com",
      "narrative": "text",
      "name": "text",
      "description": "text",
      "genre": "text",
      "audience": "text"
    }
  ],
  "extensions": {
    "value": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  },
  "expires": "2025-07-15T19:17:56.673Z",
  "ob3AwardProperties": {
    "activityStart": "2025-07-15T19:17:56.673Z",
    "activityEnd": "2025-07-15T19:17:56.673Z",
    "licenseNumber": "text",
    "role": "text"
  }
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-15T19:17:56.673Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-15T19:17:56.673Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-15T19:17:56.673Z",
        "activityEnd": "2025-07-15T19:17:56.673Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of BadgeClasses for a single Issuer

get

Authorizations

Path parameters

idOrEntityIdstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

400

Bad Request

*/*

get

GET /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new BadgeClass associated with an Issuer

post

Authorizations

Path parameters

idOrEntityIdstringRequired

Body

issuerstringOptional

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q

namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert

imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image

achievementTypestringOptional

The type of achievement

Example: Course

descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.

criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria

criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

201

Created

400

Bad Request

*/*

post

POST /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1010

{
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of BadgeClasses for authenticated user

get

Authorizations

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

400

Bad Request

*/*

get

GET /v2/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new BadgeClass

post

Authorizations

Body

issuerstringRequired

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q

namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert

descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.

imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://example.com/images/1

achievementTypestringOptional

The type of achievement

Example: Course

criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria

criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

201

BadgeClass created

400

Bad Request

*/*

post

POST /v2/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 975

{
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://example.com/images/1",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Duplicate a BadgeClass

post

Create a duplicate of the original BadgeClass with a new name

Authorizations

Path parameters

idOrEntityIdstringRequired

Body

newNamestringRequired

The new name for the duplicate badgeclass

Example: Badgeclass Copy

Responses

201

BadgeClass created

400

Bad Request

*/*

post

POST /v2/badgeclasses/{idOrEntityId}/duplicate HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "newName": "Badgeclass Copy"
}

{
  "id": "68e9d238c5afe622816febb3",
  "entityType": "BadgeClass",
  "entityId": "iOMWsaF1QbmMCofM54JlUg",
  "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
  "sourceUrl": "https://example.com/badge-classes/1",
  "originalJson": "{}",
  "createdAt": "2025-07-15T19:17:56.673Z",
  "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
  "name": "Math Expert",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "tags": [
    "text"
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "source": "local",
  "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
  "archived": true,
  "archivedDate": "2025-07-15T19:17:56.673Z",
  "archivalNote": "text",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

Get a list of ClaimCodes for a single BadgeClass

get

Authorizations

Path parameters

idOrEntityIdstringRequired

Query parameters

includeClaimCodeCountbooleanOptional

Responses

200

OK

400

Bad Request

*/*

get

GET /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-15T19:17:56.673Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new ClaimCode for a BadgeClass

post

Authorizations

Path parameters

idOrEntityIdstringRequired

Body

labelstringOptional

The label of the claim code

Example: Conference Event

limitinteger · int64Optional

The number of times the claim code can be used

Example: 10

expirationDatestring · date-timeOptional

Responses

201

Created

400

Bad Request

*/*

post

POST /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2025-07-15T19:17:56.673Z"
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-15T19:17:56.673Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Reactivate a BadgeClass by id

post

Reactivate a BadgeClass that was archived

Authorizations

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

400

Bad Request

*/*

post

POST /v2/badgeclasses/reactivate/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Reactivate a BadgeClass by ref

post

Reactivate an archived BadgeClass by its base64 encoded OpenBadge ID

Authorizations

Path parameters

refstringRequired

Responses

200

OK

400

Bad Request

*/*

post

POST /v2/badgeclasses/reactivate/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-15T19:17:56.673Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Enable a disabled ClaimCode for a BadgeClass

patch

Authorizations

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

400

Bad Request

*/*

patch

PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/enable HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-15T19:17:56.673Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Disable an enabled ClaimCode for a BadgeClass

patch

Authorizations

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

400

Bad Request

*/*

patch

PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/disable HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-15T19:17:56.673Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-15T19:17:56.673Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-15T19:17:56.673Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}