Grant a custom badge through the API

Custom badges that you have created on your forum can be granted through the API. This is a great way to award badges without having to use custom badge SQL.

To grant a badge through the API, you need to know the username of the user that you wish to grant the badge to, and the ID of the badge you wish to grant. You also need to make sure you have generated an All Users API Key from your site’s Admin/API section.

Finding your API Key

This screenshot is from my local development site. Generally, you need to be very careful about sharing your API keys:

Finding the Badge ID

You can get the Badge ID from the badge’s URL. Go to your Admin/Badges section and then click on the badge that you wish to grant. The URL will look something like this: https://forum.example.com/admin/badges/102. The last number in the URL is the badge ID.

Making the API call

To test an API call, you can try granting a badge using curl or Postman. Here is how I grant a badge from my computer’s terminal with curl.

First, to make things easier, set an api_key variable:

 api_key=yourallusersapikey

Then to grant a badge with the ID of 102 to the user bobby:

curl -X POST "https://forum.example.com/user_badges" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: $api_key" \
-H "Api-Username: system" \
-F "username=bobby" \
-F "badge_id=102" \
-F "reason=https://forum.example.com/t/whats-the-best-photo-youve-ever-taken/160/2"

The reason parameter is optional. If you supply it, it must be set to the URL of a topic or a post on your site.

You should get a JSON response with details about the badge and when it was granted.


This document is version controlled - suggest changes on github.

Last edited by @JammyDodger 2024-05-26T08:41:51Z

Check documentPerform check on document:
26 Likes

Has anybody added a badge (or flair) via Zapier to Discourse API like outlined here?

Also, seems like a great candidate for an action via the official integration, @HAWK.

3 Likes

See also How to create a custom badge with an image through the API, which shows how to upload, and also has another example of granting the badge (in python).

1 Like

What is the reason this method is not described in the API Docs at https://docs.discourse.org/?

I couldn’t find this there.

2 Likes

Because it doesn’t seem to be anyone’s job to keep those docs complete or up to date and some kind soul posted these instructions here. Generally, the documentation for the API is Reverse engineer the Discourse API and looking at the source.

6 Likes

Nice, so there is no way to automate such badge giving via API?

Example, someone who receives 5,000 likes on their replies is granted a badge.

1 Like

If you’re self-hosted, or on Enterprise, you want to Enable Badge SQL.

2 Likes

If you can’t enable badge SQL, it would be technically possible to automate this, but it would be a two step process. First, make an API request to run a Data Explorer query that returns the usernames of users who meet your criteria who have not yet been granted the badge: Run Data Explorer queries with the Discourse API. Then, use the usernames returned by that query to grant the badge via the API.

This feels kind of inefficient though. As far as I can tell, there isn’t a route that can be used to grant a badge to multiple users with a single API call, so depending on how many users qualify for the badge, you could end up making a lot of API requests.

Ultimately, this feels like the kind of thing that could be handled by the Automation plugin. There could be a recurring trigger that runs a Data Explorer query with a given query ID. Based on the fields returned by the query, the results could be used to trigger various scripts. For example, if a username field was returned by the query, it could be used to run scripts that awarded badges, added users to groups, etc.

1 Like

Won’t the have the same problems that caused the badge sql to get disabled in the first place?

1 Like

I don’t think so. Data Explorer queries are run in a transaction block that times out after 10 seconds. I think the point of that is to avoid the kind of issue that badge queries can trigger. If things weren’t configured that way, an inefficient Data Explorer query could crash the site.

Thinking about that now, I wonder if custom badge sql could have the same kind of safeguard.

4 Likes