Awards API

الأوسمة — badges a community grants its members.

Plan: every route needs the awards feature (403 FEATURE_NOT_AVAILABLE).

Who reads what:

GET /awards accepts an optional token. An approved, un-banned member gets every non-hidden award (moderators also see hidden ones). A guest of a PUBLIC community whose admin opened awards to guests gets only isGuestVisible awards, without recipients. Anyone else — a signed-in non-member, and every non-member of a PRIVATE community — gets an empty page. A PRIVATE community's guest preview uses the public endpoint, which returns opaque teasers (/api/communities/public/{slug}/awards).
Every other read requires membership.

Who writes: awards:manage (hide/unhide also awards:moderate). Uploading an icon is refused while the manager is restricted from media or suspended (403 RESTRICTION_BLOCKED) and counts against the storage quota.

11 endpoints.

Method	Path	Summary
`GET`	`/api/communities/{communityId}/awards`	List awards
`POST`	`/api/communities/{communityId}/awards`	Create an award (awards:manage)
`DELETE`	`/api/communities/{communityId}/awards/{awardId}`	Delete an award (awards:manage)
`GET`	`/api/communities/{communityId}/awards/{awardId}`	One award (members)
`PUT`	`/api/communities/{communityId}/awards/{awardId}`	Edit an award (awards:manage)
`POST`	`/api/communities/{communityId}/awards/{awardId}/grant`	Grant an award (awards:manage)
`POST`	`/api/communities/{communityId}/awards/{awardId}/hide`	Hide an award (awards:manage or awards:moderate)
`GET`	`/api/communities/{communityId}/awards/{awardId}/recipients`	Who holds an award (members)
`DELETE`	`/api/communities/{communityId}/awards/{awardId}/recipients/{userId}`	Revoke a member's award (awards:manage)
`POST`	`/api/communities/{communityId}/awards/{awardId}/unhide`	Unhide an award (awards:manage or awards:moderate)
`GET`	`/api/communities/{communityId}/awards/users/{userId}`	A member's earned awards (members)

List awards

GET /api/communities/{communityId}/awards

Auth: optional — a token changes what you can see (see "Who may read what").

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`q`	query	no	string	—
`categoryId`	query	no	string	—
`rarityId`	query	no	string	—
`page`	query	no	integer	—
`pageSize`	query	no	integer	—

Responses

Status	Description	Body
`200`	`{ success, data: Award[], page, pageSize, total, hasNext }` — empty for a caller who may not see awards	—

Create an award (awards:manage)

POST /api/communities/{communityId}/awards

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Type: AwardWriteForm

Responses

Status	Description	Body
`201`	`data` is the Award	—
`400`	Validation error	—
`403`	Missing awards:manage, RESTRICTION_BLOCKED, or FEATURE_NOT_AVAILABLE	—

Delete an award (awards:manage)

DELETE /api/communities/{communityId}/awards/{awardId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Responses

Status	Description	Body
`200`	Deleted	—
`404`	Not found	—

One award (members)

GET /api/communities/{communityId}/awards/{awardId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Responses

Status	Description	Body
`200`	`data` is the Award	—
`404`	Not found	—

Edit an award (awards:manage)

PUT /api/communities/{communityId}/awards/{awardId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Request body — multipart/form-data

Type: AwardWriteForm

Responses

Status	Description	Body
`200`	`data` is the Award	—
`403`	Missing awards:manage, RESTRICTION_BLOCKED, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Grant an award (awards:manage)

POST /api/communities/{communityId}/awards/{awardId}/grant

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Request body (required) — application/json

Field	Type	Required	Description
`audience`	enum: `all`, `moderators`, `specific`	yes	—
`targetUserIds`	string[]	no	User ids; required when audience is specific; must be members of this community
`reason`	string	no	—

Responses

Status	Description	Body
`201`	`data` reports who received it	—
`400`	Invalid audience or targets	—

Hide an award (awards:manage or awards:moderate)

POST /api/communities/{communityId}/awards/{awardId}/hide

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Responses

Status	Description	Body
`200`	`data` is the Award	—

Who holds an award (members)

GET /api/communities/{communityId}/awards/{awardId}/recipients

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Responses

Status	Description	Body
`200`	`data` lists the recipients	—

Revoke a member's award (awards:manage)

DELETE /api/communities/{communityId}/awards/{awardId}/recipients/{userId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—
`userId`	path	yes	string	—

Responses

Status	Description	Body
`200`	Revoked	—
`404`	Not found	—

Unhide an award (awards:manage or awards:moderate)

POST /api/communities/{communityId}/awards/{awardId}/unhide

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`awardId`	path	yes	string	—

Responses

Status	Description	Body
`200`	`data` is the Award	—

A member's earned awards (members)

GET /api/communities/{communityId}/awards/users/{userId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`userId`	path	yes	string	—

Responses

Status	Description	Body
`200`	`data` is Award[] (hidden awards excluded)	—