openapi: 3.1.0 info: title: Discourse API Documentation Admin Site 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: Site paths: /site.json: get: summary: Get site info tags: - Site operationId: getSite description: Can be used to fetch all categories and subcategories responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: default_archetype: type: string notification_types: type: object additionalProperties: false properties: mentioned: type: integer replied: type: integer quoted: type: integer edited: type: integer liked: type: integer private_message: type: integer invited_to_private_message: type: integer invitee_accepted: type: integer posted: type: integer watching_category_or_tag: type: integer new_features: type: integer admin_problems: type: integer moved_post: type: integer linked: type: integer granted_badge: type: integer invited_to_topic: type: integer custom: type: integer group_mentioned: type: integer group_message_summary: type: integer watching_first_post: type: integer topic_reminder: type: integer liked_consolidated: type: integer linked_consolidated: type: integer post_approved: type: integer code_review_commit_approved: type: integer membership_request_accepted: type: integer membership_request_consolidated: type: integer bookmark_reminder: type: integer reaction: type: integer votes_released: type: integer event_reminder: type: integer event_invitation: type: integer chat_mention: type: integer chat_message: type: integer chat_invitation: type: integer chat_group_mention: type: integer chat_quoted: type: integer chat_watched_thread: type: integer upcoming_change_available: type: integer upcoming_change_automatically_promoted: type: integer assigned: type: integer question_answer_user_commented: type: integer following: type: integer following_created_topic: type: integer following_replied: type: integer circles_activity: type: integer required: - mentioned - replied - quoted - edited - liked - private_message - invited_to_private_message - invitee_accepted - posted - watching_category_or_tag - moved_post - linked - granted_badge - invited_to_topic - custom - group_mentioned - group_message_summary - watching_first_post - topic_reminder - liked_consolidated - linked_consolidated - post_approved - code_review_commit_approved - membership_request_accepted - membership_request_consolidated - bookmark_reminder - reaction - votes_released - event_reminder - event_invitation - chat_mention - chat_message - chat_invitation - chat_group_mention post_types: type: object additionalProperties: false properties: regular: type: integer moderator_action: type: integer small_action: type: integer whisper: type: integer required: - regular - moderator_action - small_action - whisper trust_levels: type: object additionalProperties: false properties: newuser: type: integer basic: type: integer member: type: integer regular: type: integer leader: type: integer required: - newuser - basic - member - regular - leader user_tips: type: object additionalProperties: false properties: first_notification: type: integer topic_timeline: type: integer post_menu: type: integer topic_notification_levels: type: integer suggested_topics: type: integer required: - first_notification - topic_timeline - post_menu - topic_notification_levels - suggested_topics groups: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' automatic: type: - boolean required: - id - name - flair_url - flair_bg_color - flair_color - automatic filters: type: array items: {} periods: type: array items: {} top_menu_items: type: array items: {} anonymous_top_menu_items: type: array items: {} uncategorized_category_id: type: integer user_field_max_length: type: integer post_action_types: type: array items: type: object additionalProperties: false properties: id: type: - integer - 'null' name_key: type: - string - 'null' name: type: string description: type: string short_description: type: string is_flag: type: boolean require_message: type: boolean enabled: type: boolean applies_to: type: array is_used: type: boolean position: type: integer auto_action_type: type: boolean system: type: boolean required: - id - name_key - name - description - short_description - is_flag - require_message - enabled - applies_to - is_used - auto_action_type topic_flag_types: type: array items: type: object additionalProperties: false properties: id: type: - integer - 'null' name_key: type: - string - 'null' name: type: string description: type: string short_description: type: string is_flag: type: boolean require_message: type: boolean enabled: type: boolean applies_to: type: array is_used: type: boolean position: type: integer auto_action_type: type: boolean system: type: boolean required: - id - name_key - name - description - short_description - is_flag - require_message - enabled - applies_to - is_used - auto_action_type can_create_tag: type: boolean can_tag_topics: type: boolean can_tag_pms: type: boolean tags_filter_regexp: type: string top_tags: type: array items: type: object properties: id: type: integer name: type: string slug: type: string required: - id - name - slug wizard_required: type: boolean can_associate_groups: type: boolean email_configured: type: boolean topic_featured_link_allowed_category_ids: type: array items: {} user_themes: type: array items: type: object additionalProperties: false properties: theme_id: type: integer name: type: string default: type: boolean color_scheme_id: type: - integer - 'null' dark_color_scheme_id: type: - integer - 'null' only_theme_color_schemes: type: boolean required: - theme_id - name - default - color_scheme_id user_color_schemes: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string is_dark: type: boolean theme_id: type: - integer - 'null' colors: type: array required: - id - name - is_dark - colors default_light_color_scheme: type: - object - 'null' default_dark_color_scheme: type: - object - 'null' censored_regexp: type: array items: type: object custom_emoji_translation: type: object additionalProperties: false properties: {} watched_words_replace: type: - string - 'null' watched_words_link: type: - string - 'null' markdown_additional_options: type: object hashtag_configurations: type: object hashtag_icons: type: object displayed_about_plugin_stat_groups: type: array categories: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string color: type: string text_color: type: string style_type: type: string emoji: type: - string - 'null' icon: type: - string - 'null' slug: type: string topic_count: type: integer post_count: type: integer position: type: integer description: type: - string - 'null' description_text: type: - string - 'null' description_excerpt: type: - string - 'null' topic_url: type: string read_restricted: type: boolean permission: type: integer notification_level: type: integer topic_template: type: - string - 'null' topic_title_placeholder: type: - string - 'null' has_children: type: boolean subcategory_count: type: - integer - 'null' sort_order: type: - string - 'null' sort_ascending: type: - string - 'null' show_subcategory_list: type: boolean num_featured_topics: type: integer default_view: type: - string - 'null' subcategory_list_style: type: string default_top_period: type: string default_list_filter: type: string minimum_required_tags: type: integer navigate_to_first_post_after_read: type: boolean allowed_tags: type: array items: {} allowed_tag_groups: type: array items: {} allow_global_tags: type: boolean required_tag_groups: type: array items: type: object additionalProperties: false properties: name: type: string min_count: type: integer required: - name - min_count read_only_banner: type: - string - 'null' uploaded_logo: type: - string - 'null' uploaded_logo_dark: type: - string - 'null' uploaded_background: type: - string - 'null' uploaded_background_dark: type: - string - 'null' can_edit: type: boolean custom_fields: type: - object - 'null' additionalProperties: true parent_category_id: type: integer form_template_ids: type: array items: {} required: - id - name - color - text_color - slug - topic_count - post_count - position - topic_url - read_restricted - permission - notification_level - topic_template - topic_title_placeholder - has_children - subcategory_count - sort_order - sort_ascending - show_subcategory_list - num_featured_topics - default_view - subcategory_list_style - default_top_period - default_list_filter - minimum_required_tags - navigate_to_first_post_after_read - allowed_tags - allowed_tag_groups - allow_global_tags - required_tag_groups - read_only_banner - uploaded_logo - uploaded_logo_dark - uploaded_background - uploaded_background_dark - can_edit archetypes: type: array items: type: object additionalProperties: false properties: id: type: string name: type: string options: type: array items: {} required: - id - name - options user_fields: type: array items: {} auth_providers: type: array items: {} whispers_allowed_groups_names: type: array denied_emojis: type: array valid_flag_applies_to_types: type: array navigation_menu_site_top_tags: type: array full_name_required_for_signup: type: boolean full_name_visible_in_signup: type: boolean admin_config_login_routes: type: array required: - default_archetype - notification_types - post_types - trust_levels - groups - filters - periods - top_menu_items - anonymous_top_menu_items - uncategorized_category_id - user_field_max_length - post_action_types - topic_flag_types - can_create_tag - can_tag_topics - can_tag_pms - tags_filter_regexp - top_tags - topic_featured_link_allowed_category_ids - user_themes - user_color_schemes - default_light_color_scheme - default_dark_color_scheme - censored_regexp - custom_emoji_translation - watched_words_replace - watched_words_link - categories - archetypes - user_fields - auth_providers - full_name_required_for_signup - full_name_visible_in_signup - email_configured /site/basic-info.json: get: summary: Get site basic info tags: - Site operationId: getSiteBasicInfo description: Can be used to fetch basic info about a site responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: logo_url: type: string logo_small_url: type: string apple_touch_icon_url: type: string favicon_url: type: string title: type: string description: type: string header_primary_color: type: string header_background_color: type: string login_required: type: boolean locale: type: string include_in_discourse_discover: type: boolean mobile_logo_url: type: string required: - logo_url - logo_small_url - apple_touch_icon_url - favicon_url - title - description - header_primary_color - header_background_color - login_required - locale - include_in_discourse_discover - mobile_logo_url