openapi: 3.1.0 info: title: Discourse API Documentation Admin Badges API x-logo: url: https://docs.discourse.org/logo.svg version: latest description: 'This page contains the documentation on how to use Discourse through API calls. > Note: For any endpoints not listed you can follow the [reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576) guide to figure out how to use an API endpoint. ### Request Content-Type The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`, `multipart/form-data`, or `application/json`. ### Endpoint Names and Response Content-Type Most API endpoints provide the same content as their HTML counterparts. For example the URL `/categories` serves a list of categories, the `/categories.json` API provides the same information in JSON format. Instead of sending API requests to `/categories.json` you may also send them to `/categories` and add an `Accept: application/json` header to the request to get the JSON response. Sending requests with the `Accept` header is necessary if you want to use URLs for related endpoints returned by the API, such as pagination URLs. These URLs are returned without the `.json` prefix so you need to add the header in order to get the correct response format. ### Authentication Some endpoints do not require any authentication, pretty much anything else will require you to be authenticated. To become authenticated you will need to create an API Key from the admin panel. Once you have your API Key you can pass it in along with your API Username as an HTTP header like this: ``` curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \ -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \ -H "Api-Username: system" ``` and this is how POST requests will look: ``` curl -X POST "http://127.0.0.1:3000/categories" \ -H "Content-Type: multipart/form-data;" \ -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \ -H "Api-Username: system" \ -F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \ -F "color=49d9e9" \ -F "text_color=f0fcfd" ``` ### Boolean values If an endpoint accepts a boolean be sure to specify it as a lowercase `true` or `false` value unless noted otherwise. ' license: name: MIT url: https://docs.discourse.org/LICENSE.txt servers: - url: https://{defaultHost} variables: defaultHost: default: discourse.example.com tags: - name: Badges paths: /admin/badges.json: get: summary: List badges tags: - Badges operationId: adminListBadges responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: badges: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string grant_count: type: integer allow_title: type: boolean multiple_grant: type: boolean icon: type: string image_url: type: - string - 'null' listable: type: boolean enabled: type: boolean badge_grouping_id: type: integer system: type: boolean long_description: type: string slug: type: string manually_grantable: type: boolean query: type: - string - 'null' trigger: type: - integer - 'null' target_posts: type: boolean auto_revoke: type: boolean show_posts: type: boolean i18n_name: type: - string - 'null' image_upload_id: type: - integer - 'null' badge_type_id: type: integer show_in_post_header: type: boolean required: - id - name - description - grant_count - allow_title - multiple_grant - icon - image_url - listable - enabled - badge_grouping_id - system - long_description - slug - manually_grantable - query - trigger - target_posts - auto_revoke - show_posts - badge_type_id - image_upload_id - show_in_post_header badge_types: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string sort_order: type: integer required: - id - name - sort_order badge_groupings: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: - string - 'null' position: type: integer system: type: boolean required: - id - name - description - position - system admin_badges: type: object additionalProperties: false properties: protected_system_fields: type: array items: {} triggers: type: object additionalProperties: false properties: user_change: type: integer none: type: integer post_revision: type: integer trust_level_change: type: integer post_action: type: integer required: - user_change - none - post_revision - trust_level_change - post_action badge_ids: type: array items: {} badge_grouping_ids: type: array items: {} badge_type_ids: type: array items: {} required: - protected_system_fields - triggers - badge_ids - badge_grouping_ids - badge_type_ids required: - badges - badge_types - badge_groupings - admin_badges post: summary: Create badge tags: - Badges operationId: createBadge parameters: [] responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: badge_types: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string sort_order: type: integer required: - id - name - sort_order badge: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string grant_count: type: integer allow_title: type: boolean multiple_grant: type: boolean icon: type: string image_url: type: - string - 'null' image_upload_id: type: - integer - 'null' listable: type: boolean enabled: type: boolean badge_grouping_id: type: integer system: type: boolean long_description: type: string slug: type: string manually_grantable: type: boolean query: type: - string - 'null' trigger: type: - string - 'null' target_posts: type: boolean auto_revoke: type: boolean show_posts: type: boolean badge_type_id: type: integer show_in_post_header: type: boolean required: - id - name - description - grant_count - allow_title - multiple_grant - icon - image_url - listable - enabled - badge_grouping_id - system - long_description - slug - manually_grantable - query - trigger - target_posts - auto_revoke - show_posts - badge_type_id - image_upload_id - show_in_post_header required: - badge_types - badge requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string description: The name for the new badge. badge_type_id: type: integer description: 'The ID for the badge type. 1 for Gold, 2 for Silver, 3 for Bronze.' required: - name - badge_type_id /admin/badges/{id}.json: put: summary: Update badge tags: - Badges operationId: updateBadge parameters: - name: id in: path schema: type: integer required: true responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: badge_types: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string sort_order: type: integer required: - id - name - sort_order badge: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string grant_count: type: integer allow_title: type: boolean multiple_grant: type: boolean icon: type: string image_url: type: - string - 'null' image_upload_id: type: - integer - 'null' listable: type: boolean enabled: type: boolean badge_grouping_id: type: integer system: type: boolean long_description: type: string slug: type: string manually_grantable: type: boolean query: type: - string - 'null' trigger: type: - string - 'null' target_posts: type: boolean auto_revoke: type: boolean show_posts: type: boolean badge_type_id: type: integer show_in_post_header: type: boolean required: - id - name - description - grant_count - allow_title - multiple_grant - icon - image_url - listable - enabled - badge_grouping_id - system - long_description - slug - manually_grantable - query - trigger - target_posts - auto_revoke - show_posts - badge_type_id - image_upload_id - show_in_post_header required: - badge_types - badge requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string description: The name for the new badge. badge_type_id: type: integer description: 'The ID for the badge type. 1 for Gold, 2 for Silver, 3 for Bronze.' required: - name - badge_type_id delete: summary: Delete badge tags: - Badges operationId: deleteBadge parameters: - name: id in: path schema: type: integer required: true responses: '200': description: success response /user-badges/{username}.json: get: summary: List badges for a user tags: - Badges operationId: listUserBadges parameters: - name: username in: path schema: type: string required: true responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: badges: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string grant_count: type: integer allow_title: type: boolean multiple_grant: type: boolean icon: type: string image_url: type: - string - 'null' listable: type: boolean enabled: type: boolean badge_grouping_id: type: integer system: type: boolean slug: type: string manually_grantable: type: boolean badge_type_id: type: integer required: - id - name - description - grant_count - allow_title - multiple_grant - icon - image_url - listable - enabled - badge_grouping_id - system - slug - manually_grantable - badge_type_id badge_types: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string sort_order: type: integer required: - id - name - sort_order granted_bies: type: array items: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string flair_name: type: - string - 'null' admin: type: boolean moderator: type: boolean trust_level: type: integer required: - id - username - name - avatar_template - flair_name - admin - moderator - trust_level user_badges: type: array items: type: object additionalProperties: false properties: id: type: integer granted_at: type: string grouping_position: type: integer is_favorite: type: - string - 'null' can_favorite: type: boolean badge_id: type: integer granted_by_id: type: integer required: - id - granted_at - grouping_position - is_favorite - can_favorite - badge_id - granted_by_id required: - user_badges