Badges v1

Reference for the Badges v1 endpoints on Roblox.

Base URL: https://badges.roblox.com

Endpoints

Method	Path	Name
GET	/v1/badges/:badgeId	getBadgesBadgeid
PATCH	/v1/badges/:badgeId	patchBadgesBadgeid
POST	/v1/badges/:badgeId/icon	postBadgesBadgeidIcon
GET	/v1/badges/metadata	getBadgesMetadata
GET	/v1/universes/:universeId/badges	getUniversesUniverseidBadges
POST	/v1/universes/:universeId/badges	postUniversesUniverseidBadges
GET	/v1/universes/:universeId/free-badges-quota	getUniversesUniverseidFreeBadgesQuota
DELETE	/v1/user/badges/:badgeId	deleteUserBadgesBadgeid
GET	/v1/users/:userId/badges	getUsersUseridBadges
GET	/v1/users/:userId/badges/:badgeId/awarded-date	getUsersUseridBadgesBadgeidAwardedDate
GET	/v1/users/:userId/badges/awarded-dates	getUsersUseridBadgesAwardedDates

getBadgesBadgeid

GET /v1/badges/:badgeId

Gets badge information by the badge Id.

Usage

import { fetchApi } from 'rozod';
import { getBadgesBadgeid } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getBadgesBadgeid, {
  badgeId: /* integer */
});

Parameters

Name	Type	Required	Description
badgeId	integer	Yes	The badge Id.

Response

Field	Type	Description
id	number
name	string
description	string
displayName	string
displayDescription	string
enabled	boolean
iconImageId	number
displayIconImageId	number
created	string
updated	string
statistics	object	See below
awardingUniverse	object	See below

statistics fields:

Field	Type	Description
pastDayAwardedCount	number
awardedCount	number
winRatePercentage	number

awardingUniverse fields:

Field	Type	Description
id	number
name	string
rootPlaceId	number

Errors

Status	Description
404	1: Badge is invalid or does not exist. 3: The game is invalid or does not exist.

---

patchBadgesBadgeid

PATCH /v1/badges/:badgeId

Updates badge configuration.

Usage

import { fetchApi } from 'rozod';
import { patchBadgesBadgeid } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(patchBadgesBadgeid, {
  badgeId: /* integer */,
  body: { /* ... */ }
});

Parameters

Name	Type	Required	Description
badgeId	integer	Yes	The badge Id.

Request Body

Field	Type	Description
name	string
description	string
enabled	boolean

Response

Type: unknown

Errors

Status	Description
400	6: Text moderated. 14: Invalid badge name. 15: Invalid badge description.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: You do not have permission to manage this badge.
404	1: Badge is invalid or does not exist. 3: The game is invalid or does not exist.

---

postBadgesBadgeidIcon

POST /v1/badges/:badgeId/icon

Overwrites a badge icon with a new one.

Usage

import { fetchApi } from 'rozod';
import { postBadgesBadgeidIcon } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(postBadgesBadgeidIcon, {
  badgeId: /* integer */,
  body: { /* ... */ }
});

Parameters

Name	Type	Required	Description
badgeId	integer	Yes	The badge Id.

Request Body

Field	Type	Description
Files	File

Response

Field	Type	Description
targetId	number

Errors

Status	Description
400	6: Text moderated. 22: Icon file is not present in the request.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 2: You do not have permission to manage this badge.
404	1: Badge is invalid or does not exist.
429	13: Too many requests, try again later.

---

getBadgesMetadata

GET /v1/badges/metadata

Gets metadata about the badges system.

Usage

import { fetchApi } from 'rozod';
import { getBadgesMetadata } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getBadgesMetadata, undefined);

Response

Field	Type	Description
badgeCreationPrice	number
maxBadgeNameLength	number
maxBadgeDescriptionLength	number
defaultBadgeIconImageId	number

---

getUniversesUniverseidBadges

GET /v1/universes/:universeId/badges

Gets badges by their awarding game.

Usage

import { fetchApi } from 'rozod';
import { getUniversesUniverseidBadges } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getUniversesUniverseidBadges, {
  universeId: /* integer */,
  sortBy: /* enum */,
  cursor: /* string? */,
  sortOrder: /* enum */
});

Parameters

Name	Type	Required	Description
universeId	integer	Yes	The universe Id.
sortBy	enum	Yes	The key to sort badges by.
cursor	string?	No	The paging cursor for the previous or next page.
sortOrder	enum	Yes	The order the results are sorted in.

Response

Field	Type	Description
previousPageCursor	string
nextPageCursor	string
data	object[]	See below

data[] item fields:

Field	Type	Description
id	number
name	string
description	string
displayName	string
displayDescription	string
enabled	boolean
iconImageId	number
displayIconImageId	number
created	string
updated	string
statistics	object	See below
awardingUniverse	object	See below

statistics fields:

Field	Type	Description
pastDayAwardedCount	number
awardedCount	number
winRatePercentage	number

awardingUniverse fields:

Field	Type	Description
id	number
name	string
rootPlaceId	number

Errors

Status	Description
400	26: The pagination cursor is invalid or incompatible with the current request.
404	3: The game is invalid or does not exist.

---

postUniversesUniverseidBadges

POST /v1/universes/:universeId/badges

Creates a new badge.

Usage

import { fetchApi } from 'rozod';
import { postUniversesUniverseidBadges } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(postUniversesUniverseidBadges, {
  universeId: /* integer */,
  body: { /* ... */ }
});

Parameters

Name	Type	Required	Description
universeId	integer	Yes	The ID of the universe to create the badge for.

Request Body

Field	Type	Description
name	string
description	string
paymentSourceType	`“User”	“Group”`
files	File
expectedCost	number
isActive	boolean

Response

Field	Type	Description
id	number
name	string
description	string
displayName	string
displayDescription	string
enabled	boolean
iconImageId	number
displayIconImageId	number
awarder	object	See below
statistics	object	See below
created	string
updated	string

awarder fields:

Field	Type	Description
id	number
type	'Place'
name	string

statistics fields:

Field	Type	Description
pastDayAwardedCount	number
awardedCount	number
winRatePercentage	number

Errors

Status	Description
400	11: The badge icon is invalid. 14: Invalid badge name. 15: Invalid badge description. 16: Payment source is invalid. 18: Expected badge cost is different from the actual badge cost.
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed 6: Text moderated. 12: You do not have permission to manage this game's badges. 17: Insufficient funds.
404	3: The game is invalid or does not exist.
429	13: Too many requests, try again later.

---

getUniversesUniverseidFreeBadgesQuota

GET /v1/universes/:universeId/free-badges-quota

Gets the number of free badges left for the current UTC day by their awarding game.

Usage

import { fetchApi } from 'rozod';
import { getUniversesUniverseidFreeBadgesQuota } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getUniversesUniverseidFreeBadgesQuota, {
  universeId: /* integer */
});

Parameters

Name	Type	Required	Description
universeId	integer	Yes	The universe Id.

Response

Type: integer

Errors

Status	Description
404	3: The game is invalid or does not exist.

---

deleteUserBadgesBadgeid

DELETE /v1/user/badges/:badgeId

Removes a badge from the authenticated user.

Usage

import { fetchApi } from 'rozod';
import { deleteUserBadgesBadgeid } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(deleteUserBadgesBadgeid, {
  badgeId: /* integer */
});

Parameters

Name	Type	Required	Description
badgeId	integer	Yes	The badge Id.

Response

Type: unknown

Errors

Status	Description
401	0: Authorization has been denied for this request.
403	0: Token Validation Failed
404	1: Badge is invalid or does not exist.

---

getUsersUseridBadges

GET /v1/users/:userId/badges

Gets a list of badges a user has been awarded.

Usage

import { fetchApi } from 'rozod';
import { getUsersUseridBadges } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getUsersUseridBadges, {
  userId: /* integer */,
  cursor: /* string? */,
  sortOrder: /* enum */
});

Parameters

Name	Type	Required	Description
userId	integer	Yes	The user Id.
cursor	string?	No	The paging cursor for the previous or next page.
sortOrder	enum	Yes	The order the results are sorted in.

Response

Field	Type	Description
previousPageCursor	string
nextPageCursor	string
data	object[]	See below

data[] item fields:

Field	Type	Description
creator	object	See below
id	number
name	string
description	string
displayName	string
displayDescription	string
enabled	boolean
iconImageId	number
displayIconImageId	number
awarder	object	See below
statistics	object	See below
created	string
updated	string

creator fields:

Field	Type	Description
id	number
name	string
type	string

awarder fields:

Field	Type	Description
id	number
type	'Place'
name	string

statistics fields:

Field	Type	Description
pastDayAwardedCount	number
awardedCount	number
winRatePercentage	number

Errors

Status	Description
404	4: User is invalid or does not exist.

---

getUsersUseridBadgesBadgeidAwardedDate

GET /v1/users/:userId/badges/:badgeId/awarded-date

Gets timestamp for when a single badge was awarded to a user.

Usage

import { fetchApi } from 'rozod';
import { getUsersUseridBadgesBadgeidAwardedDate } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getUsersUseridBadgesBadgeidAwardedDate, {
  userId: /* integer */,
  badgeId: /* integer */
});

Parameters

Name	Type	Required	Description
userId	integer	Yes	User id.
badgeId	integer	Yes	Badge id.

Response

Type: unknown

Errors

Status	Description
404	4: User is invalid or does not exist.

---

getUsersUseridBadgesAwardedDates

GET /v1/users/:userId/badges/awarded-dates

Gets timestamps for when badges were awarded to a user.

Usage

import { fetchApi } from 'rozod';
import { getUsersUseridBadgesAwardedDates } from 'rozod/endpoints/badgesv1';

const data = await fetchApi(getUsersUseridBadgesAwardedDates, {
  userId: /* integer */,
  badgeIds: /* number */
});

Parameters

Name	Type	Required	Description
userId	integer	Yes	The user Id.
badgeIds	number	Yes	The CSV of badge Ids.

Response

Field	Type	Description
data	object[]	See below

data[] item fields:

Field	Type	Description
badgeId	number
awardedDate	string

Errors

Status	Description
400	5: Too many badge Ids.
404	4: User is invalid or does not exist.

---