openapi: 3.1.0 info: title: Discourse API Documentation 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 security: - key: [] username: [] components: securitySchemes: key: description: Discourse Authentication Token type: apiKey in: header name: Api-Key username: description: Discourse Authentication Username type: apiKey in: header name: Api-Username paths: "/admin/backups.json": get: summary: List backups tags: - Backups operationId: getBackups responses: '200': description: success response content: application/json: schema: type: array minItems: 1 uniqueItems: true items: type: object properties: filename: type: string size: type: integer last_modified: type: string required: - filename - size - last_modified post: summary: Create backup tags: - Backups operationId: createBackup parameters: [] responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success requestBody: content: application/json: schema: additionalProperties: false properties: with_uploads: type: boolean required: - with_uploads "/admin/backups/{filename}": put: summary: Send download backup email tags: - Backups operationId: sendDownloadBackupEmail parameters: - name: filename in: path required: true schema: type: string responses: '200': description: success response get: summary: Download backup tags: - Backups operationId: downloadBackup parameters: - name: filename in: path required: true schema: type: string - name: token in: query required: true schema: type: string responses: '200': description: success response "/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' badge_type_id: type: integer 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 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' 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 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 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' 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 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 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 "/categories.json": post: summary: Creates a category tags: - Categories operationId: createCategory parameters: [] responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: category: type: object additionalProperties: false properties: id: type: integer name: type: string color: type: string text_color: type: string 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 - 'null' read_restricted: type: boolean permission: type: - integer - 'null' notification_level: type: integer can_edit: type: boolean topic_template: type: - string - 'null' form_template_ids: type: array items: {} has_children: type: - boolean - '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 custom_fields: type: object additionalProperties: false properties: {} 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 category_setting: auto_bump_cooldown_days: 1 num_auto_bump_daily: require_reply_approval: require_topic_approval: read_only_banner: type: - string - 'null' available_groups: type: array items: {} auto_close_hours: type: - string - 'null' auto_close_based_on_last_post: type: boolean allow_unlimited_owner_edits_on_first_post: type: boolean default_slow_mode_seconds: type: - string - 'null' group_permissions: type: array items: type: object additionalProperties: false properties: permission_type: type: integer group_name: type: string required: - permission_type - group_name email_in: type: - string - 'null' email_in_allow_strangers: type: boolean mailinglist_mirror: type: boolean all_topics_wiki: type: boolean can_delete: type: boolean allow_badges: type: boolean topic_featured_link_allowed: type: boolean search_priority: type: integer uploaded_logo: type: - string - 'null' uploaded_logo_dark: type: - string - 'null' uploaded_background: type: - string - 'null' uploaded_background_dark: type: - string - 'null' required: - id - name - color - text_color - slug - topic_count - post_count - position - description - description_text - description_excerpt - topic_url - read_restricted - permission - notification_level - can_edit - topic_template - has_children - 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 - custom_fields - required_tag_groups - read_only_banner - available_groups - auto_close_hours - auto_close_based_on_last_post - allow_unlimited_owner_edits_on_first_post - default_slow_mode_seconds - group_permissions - email_in - email_in_allow_strangers - mailinglist_mirror - all_topics_wiki - can_delete - allow_badges - topic_featured_link_allowed - search_priority - uploaded_logo - uploaded_logo_dark - uploaded_background - uploaded_background_dark required: - category requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string color: type: string example: 49d9e9 text_color: type: string example: f0fcfd parent_category_id: type: integer allow_badges: type: boolean slug: type: string topic_featured_links_allowed: type: boolean permissions: type: object additionalProperties: true properties: everyone: type: integer example: 1 staff: type: integer search_priority: type: integer form_template_ids: type: array items: {} required: - name get: summary: Retrieves a list of categories tags: - Categories operationId: listCategories parameters: - name: include_subcategories in: query schema: type: boolean enum: - true responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: category_list: type: object additionalProperties: false properties: can_create_category: type: boolean can_create_topic: type: boolean categories: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string color: type: string text_color: type: string 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 - 'null' read_restricted: type: boolean permission: type: integer notification_level: type: integer can_edit: type: boolean topic_template: type: - string - 'null' has_children: type: boolean 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 topics_day: type: integer topics_week: type: integer topics_month: type: integer topics_year: type: integer topics_all_time: type: integer is_uncategorized: type: boolean subcategory_ids: type: array items: {} subcategory_list: type: - array - 'null' items: {} uploaded_logo: type: - string - 'null' uploaded_logo_dark: type: - string - 'null' uploaded_background: type: - string - 'null' uploaded_background_dark: type: - string - 'null' required: - id - name - color - text_color - slug - topic_count - post_count - position - description - description_text - description_excerpt - topic_url - read_restricted - permission - notification_level - can_edit - topic_template - has_children - 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 - topics_day - topics_week - topics_month - topics_year - topics_all_time - subcategory_ids - uploaded_logo - uploaded_logo_dark - uploaded_background - uploaded_background_dark required: - can_create_category - can_create_topic - categories required: - category_list "/categories/{id}.json": put: summary: Updates a category tags: - Categories operationId: updateCategory parameters: - name: id in: path schema: type: integer required: true responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: success: type: string category: type: object additionalProperties: false properties: id: type: integer name: type: string color: type: string text_color: type: string 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 - 'null' read_restricted: type: boolean permission: type: - integer - 'null' notification_level: type: integer can_edit: type: boolean topic_template: type: - string - 'null' form_template_ids: type: array items: {} has_children: type: - boolean - '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 custom_fields: type: object additionalProperties: false properties: {} 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 category_setting: auto_bump_cooldown_days: 1 num_auto_bump_daily: require_reply_approval: require_topic_approval: read_only_banner: type: - string - 'null' available_groups: type: array items: {} auto_close_hours: type: - string - 'null' auto_close_based_on_last_post: type: boolean allow_unlimited_owner_edits_on_first_post: type: boolean default_slow_mode_seconds: type: - string - 'null' group_permissions: type: array items: type: object additionalProperties: false properties: permission_type: type: integer group_name: type: string required: - permission_type - group_name email_in: type: - string - 'null' email_in_allow_strangers: type: boolean mailinglist_mirror: type: boolean all_topics_wiki: type: boolean can_delete: type: boolean allow_badges: type: boolean topic_featured_link_allowed: type: boolean search_priority: type: integer uploaded_logo: type: - string - 'null' uploaded_logo_dark: type: - string - 'null' uploaded_background: type: - string - 'null' uploaded_background_dark: type: - string - 'null' required: - id - name - color - text_color - slug - topic_count - post_count - position - description - description_text - description_excerpt - topic_url - read_restricted - permission - notification_level - can_edit - topic_template - form_template_ids - has_children - 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 - custom_fields - required_tag_groups - read_only_banner - available_groups - auto_close_hours - auto_close_based_on_last_post - allow_unlimited_owner_edits_on_first_post - default_slow_mode_seconds - group_permissions - email_in - email_in_allow_strangers - mailinglist_mirror - all_topics_wiki - can_delete - allow_badges - topic_featured_link_allowed - search_priority - uploaded_logo - uploaded_logo_dark - uploaded_background - uploaded_background_dark required: - success - category requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string color: type: string example: 49d9e9 text_color: type: string example: f0fcfd parent_category_id: type: integer allow_badges: type: boolean slug: type: string topic_featured_links_allowed: type: boolean permissions: type: object additionalProperties: true properties: everyone: type: integer example: 1 staff: type: integer search_priority: type: integer form_template_ids: type: array items: {} required: - name "/c/{slug}/{id}.json": get: summary: List topics tags: - Categories operationId: listCategoryTopics parameters: - name: slug in: path schema: type: string required: true - name: id in: path schema: type: integer required: true responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: users: type: array items: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template primary_groups: type: array items: {} topic_list: type: object additionalProperties: false properties: can_create_topic: type: boolean per_page: type: integer top_tags: type: array items: {} topics: type: array items: type: object additionalProperties: false properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean pinned: type: boolean unpinned: type: - string - 'null' excerpt: type: string visible: type: boolean closed: type: boolean archived: type: boolean bookmarked: type: - string - 'null' liked: type: - string - 'null' views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: integer pinned_globally: type: boolean featured_link: type: - string - 'null' posters: type: array items: type: object additionalProperties: false properties: extras: type: string description: type: string user_id: type: integer primary_group_id: type: - string - 'null' required: - extras - description - user_id - primary_group_id required: - id - title - fancy_title - slug - posts_count - reply_count - highest_post_number - image_url - created_at - last_posted_at - bumped - bumped_at - archetype - unseen - pinned - unpinned - excerpt - visible - closed - archived - bookmarked - liked - views - like_count - has_summary - last_poster_username - category_id - pinned_globally - featured_link - posters required: - can_create_topic - per_page - topics required: - topic_list "/c/{id}/show.json": get: summary: Show category tags: - Categories operationId: getCategory parameters: - name: id in: path schema: type: integer required: true responses: '200': description: response content: application/json: schema: additionalProperties: false properties: category: type: object additionalProperties: false properties: id: type: integer name: type: string color: type: string text_color: type: string 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 - 'null' read_restricted: type: boolean permission: type: - integer - 'null' notification_level: type: integer can_edit: type: boolean topic_template: type: - string - 'null' form_template_ids: type: array items: {} has_children: type: - boolean - '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 custom_fields: type: object additionalProperties: false properties: {} 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 category_setting: auto_bump_cooldown_days: 1 num_auto_bump_daily: require_reply_approval: require_topic_approval: read_only_banner: type: - string - 'null' available_groups: type: array items: {} auto_close_hours: type: - string - 'null' auto_close_based_on_last_post: type: boolean allow_unlimited_owner_edits_on_first_post: type: boolean default_slow_mode_seconds: type: - string - 'null' group_permissions: type: array items: type: object additionalProperties: false properties: permission_type: type: integer group_name: type: string required: - permission_type - group_name email_in: type: - string - 'null' email_in_allow_strangers: type: boolean mailinglist_mirror: type: boolean all_topics_wiki: type: boolean can_delete: type: boolean allow_badges: type: boolean topic_featured_link_allowed: type: boolean search_priority: type: integer uploaded_logo: type: - string - 'null' uploaded_logo_dark: type: - string - 'null' uploaded_background: type: - string - 'null' uploaded_background_dark: type: - string - 'null' required: - id - name - color - text_color - slug - topic_count - post_count - position - description - description_text - description_excerpt - topic_url - read_restricted - permission - notification_level - can_edit - topic_template - has_children - 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 - custom_fields - required_tag_groups - read_only_banner - available_groups - auto_close_hours - auto_close_based_on_last_post - allow_unlimited_owner_edits_on_first_post - default_slow_mode_seconds - group_permissions - email_in - email_in_allow_strangers - mailinglist_mirror - all_topics_wiki - can_delete - allow_badges - topic_featured_link_allowed - search_priority - uploaded_logo - uploaded_logo_dark - uploaded_background - uploaded_background_dark required: - category "/admin/groups.json": post: summary: Create a group tags: - Groups operationId: createGroup parameters: [] responses: '200': description: group created content: application/json: schema: additionalProperties: false properties: basic_group: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean can_edit_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state required: - basic_group requestBody: content: application/json: schema: additionalProperties: false properties: group: type: object additionalProperties: false properties: name: type: string full_name: type: string bio_raw: type: string description: About Group usernames: type: string description: comma,separated owner_usernames: type: string description: comma,separated automatic_membership_email_domains: type: string description: pipe|separated visibility_level: type: integer primary_group: type: boolean flair_icon: type: string flair_upload_id: type: integer flair_bg_color: type: string public_admission: type: boolean public_exit: type: boolean default_notification_level: type: integer muted_category_ids: type: array items: type: integer regular_category_ids: type: array items: type: integer watching_category_ids: type: array items: type: integer tracking_category_ids: type: array items: type: integer watching_first_post_category_ids: type: array items: type: integer required: - name required: - group "/admin/groups/{id}.json": delete: summary: Delete a group tags: - Groups operationId: deleteGroup parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success "/groups/{id}.json": put: summary: Update a group tags: - Groups operationId: updateGroup parameters: - name: id in: path required: true schema: type: integer responses: '200': description: success response content: application/json: schema: type: object properties: success: type: string example: OK requestBody: content: application/json: schema: additionalProperties: false properties: group: type: object additionalProperties: false properties: name: type: string full_name: type: string bio_raw: type: string description: About Group usernames: type: string description: comma,separated owner_usernames: type: string description: comma,separated automatic_membership_email_domains: type: string description: pipe|separated visibility_level: type: integer primary_group: type: boolean flair_icon: type: string flair_upload_id: type: integer flair_bg_color: type: string public_admission: type: boolean public_exit: type: boolean default_notification_level: type: integer muted_category_ids: type: array items: type: integer regular_category_ids: type: array items: type: integer watching_category_ids: type: array items: type: integer tracking_category_ids: type: array items: type: integer watching_first_post_category_ids: type: array items: type: integer required: - name required: - group get: summary: Get a group tags: - Groups operationId: getGroup parameters: - name: id in: path example: name description: Use group name instead of id required: true schema: type: string responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: group: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' is_group_user: type: boolean members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean can_edit_group: type: boolean publish_read_state: type: boolean is_group_owner_display: type: boolean mentionable: type: boolean messageable: type: boolean automatic_membership_email_domains: type: - string - 'null' smtp_updated_at: type: - string - 'null' smtp_updated_by: type: - object - 'null' smtp_enabled: type: boolean smtp_server: type: - string - 'null' smtp_port: type: - string - 'null' smtp_ssl: type: - string - 'null' imap_enabled: type: boolean imap_updated_at: type: - string - 'null' imap_updated_by: type: - object - 'null' imap_server: type: - string - 'null' imap_port: type: - string - 'null' imap_ssl: type: - string - 'null' imap_mailbox_name: type: string imap_mailboxes: type: array items: {} email_username: type: - string - 'null' email_from_alias: type: - string - 'null' email_password: type: - string - 'null' imap_last_error: type: - string - 'null' imap_old_emails: type: - string - 'null' imap_new_emails: type: - string - 'null' message_count: type: integer allow_unknown_sender_topic_replies: type: boolean associated_group_ids: type: array items: {} watching_category_ids: type: array items: {} tracking_category_ids: type: array items: {} watching_first_post_category_ids: type: array items: {} regular_category_ids: type: array items: {} muted_category_ids: type: array items: {} watching_tags: type: array items: {} watching_first_post_tags: type: array items: {} tracking_tags: type: array items: {} regular_tags: type: array items: {} muted_tags: type: array items: {} required: - id - automatic - name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - is_group_user - members_visibility_level - can_see_members - can_admin_group - publish_read_state - is_group_owner_display - mentionable - messageable - automatic_membership_email_domains - smtp_server - smtp_port - smtp_ssl - imap_server - imap_port - imap_ssl - imap_mailbox_name - imap_mailboxes - email_username - email_password - imap_last_error - imap_old_emails - imap_new_emails - message_count - allow_unknown_sender_topic_replies - watching_category_ids - tracking_category_ids - watching_first_post_category_ids - regular_category_ids - muted_category_ids extras: type: object additionalProperties: false properties: visible_group_names: type: array items: {} required: - visible_group_names required: - group - extras "/groups/{id}/members.json": get: summary: List group members tags: - Groups operationId: listGroupMembers parameters: - name: id in: path example: name description: Use group name instead of id required: true schema: type: string responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: members: type: array items: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string title: type: - string - 'null' last_posted_at: type: string last_seen_at: type: string added_at: type: string timezone: type: string required: - id - username - name - avatar_template - title - last_posted_at - last_seen_at - added_at - timezone owners: type: array items: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string title: type: - string - 'null' last_posted_at: type: string last_seen_at: type: string added_at: type: string timezone: type: string required: - id - username - name - avatar_template - title - last_posted_at - last_seen_at - added_at - timezone meta: type: object additionalProperties: false properties: total: type: integer limit: type: integer offset: type: integer required: - total - limit - offset required: - members - owners - meta put: summary: Add group members tags: - Groups operationId: addGroupMembers parameters: - name: id in: path required: true schema: type: integer responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: success: type: string usernames: type: array items: {} emails: type: array items: {} required: - success - usernames - emails requestBody: content: application/json: schema: additionalProperties: false properties: usernames: type: string description: comma separated list example: username1,username2 delete: summary: Remove group members tags: - Groups operationId: removeGroupMembers parameters: - name: id in: path required: true schema: type: integer responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: success: type: string usernames: type: array items: {} skipped_usernames: type: array items: {} required: - success - usernames - skipped_usernames requestBody: content: application/json: schema: additionalProperties: false properties: usernames: type: string description: comma separated list example: username1,username2 "/groups.json": get: summary: List groups tags: - Groups operationId: listGroups responses: '200': description: response content: application/json: schema: additionalProperties: false properties: groups: type: array items: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string display_name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' is_group_user: type: boolean is_group_owner: type: boolean members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean can_edit_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - display_name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state extras: type: object additionalProperties: false properties: type_filters: type: array items: {} required: - type_filters total_rows_groups: type: integer load_more_groups: type: string required: - groups - extras - total_rows_groups - load_more_groups "/invites.json": post: summary: Create an invite tags: - Invites operationId: createInvite parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string responses: '200': description: success response content: application/json: schema: type: object properties: id: type: integer example: 42 link: type: string example: http://example.com/invites/9045fd767efe201ca60c6658bcf14158 email: type: string example: not-a-user-yet@example.com emailed: type: boolean example: false custom_message: type: - string - 'null' example: Hello world! topics: type: array items: {} example: [] groups: type: array items: {} example: [] created_at: type: string example: '2021-01-01T12:00:00.000Z' updated_at: type: string example: '2021-01-01T12:00:00.000Z' expires_at: type: string example: '2021-02-01T12:00:00.000Z' expired: type: boolean example: false requestBody: content: application/json: schema: type: object properties: email: type: string example: not-a-user-yet@example.com description: required for email invites only skip_email: type: boolean default: false custom_message: type: string description: optional, for email invites max_redemptions_allowed: type: integer example: 5 default: 1 description: optional, for link invites topic_id: type: integer group_ids: type: string description: Optional, either this or `group_names`. Comma separated list for multiple ids. example: '42,43' group_names: type: string description: Optional, either this or `group_ids`. Comma separated list for multiple names. example: foo,bar expires_at: type: string description: optional, if not supplied, the invite_expiry_days site setting is used "/notifications.json": get: summary: Get the notifications that belong to the current user tags: - Notifications operationId: getNotifications responses: '200': description: notifications content: application/json: schema: type: object properties: notifications: type: array items: type: object properties: id: type: integer user_id: type: integer notification_type: type: integer read: type: boolean created_at: type: string post_number: type: - string - 'null' topic_id: type: - integer - 'null' slug: type: - string - 'null' data: type: object properties: badge_id: type: integer badge_name: type: string badge_slug: type: string badge_title: type: boolean username: type: string total_rows_notifications: type: integer seen_notification_id: type: integer load_more_notifications: type: string "/notifications/mark-read.json": put: summary: Mark notifications as read tags: - Notifications operationId: markNotificationsAsRead parameters: [] responses: '200': description: notifications marked read content: application/json: schema: type: object properties: success: type: string requestBody: content: application/json: schema: type: object properties: id: type: integer description: "(optional) Leave off to mark all notifications as read" "/posts.json": get: summary: List latest posts across topics tags: - Posts operationId: listPosts parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: before in: query description: Load posts with an id lower than this value. Useful for pagination. required: false schema: type: string responses: '200': description: latest posts content: application/json: schema: type: object properties: latest_posts: type: array items: type: object properties: id: type: integer name: type: string username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: number yours: type: boolean topic_id: type: integer topic_slug: type: string topic_title: type: string topic_html_title: type: string category_id: type: integer display_username: type: string primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' raw: type: string actions_summary: type: array items: type: object properties: id: type: integer can_act: type: boolean moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer post: summary: Creates a new topic, a new post, or a private message tags: - Posts - Topics - Private Messages operationId: createTopicPostPM parameters: [] responses: '200': description: post created content: application/json: schema: additionalProperties: false properties: id: type: integer name: type: - string - 'null' username: type: string avatar_template: type: string created_at: type: string raw: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string display_username: type: - string - 'null' primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' bookmarked: type: boolean actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer can_act: type: boolean required: - id - can_act moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer draft_sequence: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer mentioned_users: type: array items: {} required: - id - name - username - avatar_template - created_at - cooked - post_number - post_type - updated_at - reply_count - reply_to_post_number - quote_count - incoming_link_count - reads - readers_count - score - yours - topic_id - topic_slug - display_username - primary_group_name - flair_name - flair_url - flair_bg_color - flair_color - version - can_edit - can_delete - can_recover - can_wiki - user_title - bookmarked - actions_summary - moderator - admin - staff - user_id - draft_sequence - hidden - trust_level - deleted_at - user_deleted - edit_reason - can_view_edit_history - wiki - reviewable_id - reviewable_score_count - reviewable_score_pending_count requestBody: content: application/json: schema: additionalProperties: false properties: title: type: string description: Required if creating a new topic or new private message. raw: type: string topic_id: type: integer description: Required if creating a new post. category: type: integer description: Optional if creating a new topic, and ignored if creating a new post. target_recipients: type: string description: Required for private message, comma separated. example: blake,sam target_usernames: type: string description: Deprecated. Use target_recipients instead. deprecated: true archetype: type: string description: Required for new private message. example: private_message created_at: type: string reply_to_post_number: type: integer description: Optional, the post number to reply to inside a topic. embed_url: type: string description: Provide a URL from a remote system to associate a forum topic with that URL, typically for using Discourse as a comments system for an external blog. external_id: type: string description: Provide an external_id from a remote system to associate a forum topic with that id. required: - raw "/posts/{id}.json": get: summary: Retrieve a single post tags: - Posts operationId: getPost description: | This endpoint can be used to get the number of likes on a post using the `actions_summary` property in the response. `actions_summary` responses with the id of `2` signify a `like`. If there are no `actions_summary` items with the id of `2`, that means there are 0 likes. Other ids likely refer to various different flag types. parameters: - name: id in: path schema: type: string required: true responses: '200': description: single post content: application/json: schema: additionalProperties: true properties: id: type: integer username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' bookmarked: type: boolean raw: type: string actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer description: "`2`: like, `3`, `4`, `6`, `7`, `8`: flag" count: type: integer acted: type: boolean can_undo: type: boolean can_act: type: boolean required: - id moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer mentioned_users: type: array items: {} name: type: - string - 'null' display_username: type: - string - 'null' required: - id - username - avatar_template - created_at - cooked - post_number - post_type - updated_at - reply_count - reply_to_post_number - quote_count - incoming_link_count - reads - readers_count - score - yours - topic_id - topic_slug - primary_group_name - flair_name - flair_url - flair_bg_color - flair_color - version - can_edit - can_delete - can_recover - can_wiki - user_title - bookmarked - raw - actions_summary - moderator - admin - staff - user_id - hidden - trust_level - deleted_at - user_deleted - edit_reason - can_view_edit_history - wiki - reviewable_id - reviewable_score_count - reviewable_score_pending_count put: summary: Update a single post tags: - Posts operationId: updatePost parameters: - name: id in: path schema: type: string required: true responses: '200': description: post updated content: application/json: schema: additionalProperties: false properties: post: type: object additionalProperties: false properties: id: type: integer username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' bookmarked: type: boolean raw: type: string actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer can_act: type: boolean required: - id - can_act moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer draft_sequence: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer mentioned_users: type: array items: {} name: type: - string - 'null' display_username: type: - string - 'null' required: - id - username - avatar_template - created_at - cooked - post_number - post_type - updated_at - reply_count - reply_to_post_number - quote_count - incoming_link_count - reads - readers_count - score - yours - topic_id - topic_slug - primary_group_name - flair_name - flair_url - flair_bg_color - flair_color - version - can_edit - can_delete - can_recover - can_wiki - user_title - bookmarked - raw - actions_summary - moderator - admin - staff - user_id - draft_sequence - hidden - trust_level - deleted_at - user_deleted - edit_reason - can_view_edit_history - wiki - reviewable_id - reviewable_score_count - reviewable_score_pending_count required: - post requestBody: content: application/json: schema: additionalProperties: false properties: post: type: object additionalProperties: false properties: raw: type: string edit_reason: type: string required: - raw delete: summary: delete a single post tags: - Posts operationId: deletePost parameters: - name: id in: path schema: type: integer required: true responses: '200': description: success response requestBody: content: application/json: schema: additionalProperties: false properties: force_destroy: type: boolean example: true description: The `SiteSetting.can_permanently_delete` needs to be enabled first before this param can be used. Also this endpoint needs to be called first without `force_destroy` and then followed up with a second call 5 minutes later with `force_destroy` to permanently delete. "/posts/{id}/replies.json": get: summary: List replies to a post tags: - Posts operationId: postReplies parameters: - name: id in: path schema: type: string required: true responses: '200': description: post replies content: application/json: schema: type: array minItems: 1 uniqueItems: true items: type: object properties: id: type: integer name: type: - string - 'null' username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: integer quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string display_username: type: - string - 'null' primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' reply_to_user: type: object additionalProperties: false properties: username: type: string name: type: string avatar_template: type: string required: - username - avatar_template bookmarked: type: boolean actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer can_act: type: boolean required: - id - can_act moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer required: - id - name - username - avatar_template - created_at - cooked - post_number - post_type - updated_at - reply_count - reply_to_post_number - quote_count - incoming_link_count - reads - readers_count - score - yours - topic_id - topic_slug - display_username - primary_group_name - flair_name - flair_url - flair_bg_color - flair_color - version - can_edit - can_delete - can_recover - can_see_hidden_post - can_wiki - user_title - reply_to_user - bookmarked - actions_summary - moderator - admin - staff - user_id - hidden - trust_level - deleted_at - user_deleted - edit_reason - can_view_edit_history - wiki - reviewable_id - reviewable_score_count - reviewable_score_pending_count "/posts/{id}/locked.json": put: summary: Lock a post from being edited tags: - Posts operationId: lockPost parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: post updated content: application/json: schema: type: object properties: locked: type: boolean requestBody: content: application/json: schema: type: object properties: locked: type: string required: - locked "/post_actions.json": post: summary: Like a post and other actions tags: - Posts operationId: performPostAction parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string responses: '200': description: post updated content: application/json: schema: type: object properties: id: type: integer name: type: string username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: number yours: type: boolean topic_id: type: integer topic_slug: type: string display_username: type: string primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_wiki: type: boolean user_title: type: - string - 'null' actions_summary: type: array items: type: object properties: id: type: integer count: type: integer acted: type: boolean can_undo: type: boolean moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean notice: type: object reviewable_id: type: - string - 'null' reviewable_score_count: type: integer reviewable_score_pending_count: type: integer requestBody: content: application/json: schema: type: object properties: id: type: integer post_action_type_id: type: integer flag_topic: type: boolean required: - id - post_action_type_id "/topics/private-messages/{username}.json": get: summary: Get a list of private messages for a user tags: - Private Messages operationId: listUserPrivateMessages parameters: - name: username in: path schema: type: string required: true responses: '200': description: private messages content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer username: type: string name: type: string avatar_template: type: string primary_groups: type: array items: {} topic_list: type: object properties: can_create_topic: type: boolean draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer per_page: type: integer topics: type: array items: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean last_read_post_number: type: integer unread_posts: type: integer pinned: type: boolean unpinned: type: - string - 'null' visible: type: boolean closed: type: boolean archived: type: boolean notification_level: type: integer bookmarked: type: boolean liked: type: boolean views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: - string - 'null' pinned_globally: type: boolean featured_link: type: - string - 'null' allowed_user_count: type: integer posters: type: array items: type: object properties: extras: type: string description: type: string user_id: type: integer primary_group_id: type: - string - 'null' participants: type: array items: type: object properties: extras: type: string description: type: - string - 'null' user_id: type: integer primary_group_id: type: - string - 'null' "/topics/private-messages-sent/{username}.json": get: summary: Get a list of private messages sent for a user tags: - Private Messages operationId: getUserSentPrivateMessages parameters: - name: username in: path schema: type: string required: true responses: '200': description: private messages content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string primary_groups: type: array items: {} topic_list: type: object properties: can_create_topic: type: boolean draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer per_page: type: integer topics: type: array items: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean last_read_post_number: type: integer unread_posts: type: integer pinned: type: boolean unpinned: type: - string - 'null' visible: type: boolean closed: type: boolean archived: type: boolean notification_level: type: integer bookmarked: type: boolean liked: type: boolean views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: - string - 'null' pinned_globally: type: boolean featured_link: type: - string - 'null' allowed_user_count: type: integer posters: type: array items: type: object properties: extras: type: string description: type: string user_id: type: integer primary_group_id: type: - string - 'null' participants: type: array items: {} "/search.json": get: summary: Search for a term tags: - Search operationId: search parameters: - name: q in: query example: 'api @blake #support tags:api after:2021-06-04 in:unseen in:open order:latest_topic' description: | The query string needs to be url encoded and is made up of the following options: - Search term. This is just a string. Usually it would be the first item in the query. - `@`: Use the `@` followed by the username to specify posts by this user. - `#`: Use the `#` followed by the category slug to search within this category. - `tags:`: `api,solved` or for posts that have all the specified tags `api+solved`. - `before:`: `yyyy-mm-dd` - `after:`: `yyyy-mm-dd` - `order:`: `latest`, `likes`, `views`, `latest_topic` - `assigned:`: username (without `@`) - `in:`: `title`, `likes`, `personal`, `messages`, `seen`, `unseen`, `posted`, `created`, `watching`, `tracking`, `bookmarks`, `assigned`, `unassigned`, `first`, `pinned`, `wiki` - `with:`: `images` - `status:`: `open`, `closed`, `public`, `archived`, `noreplies`, `single_user`, `solved`, `unsolved` - `group:`: group_name or group_id - `group_messages:`: group_name or group_id - `min_posts:`: 1 - `max_posts:`: 10 - `min_views:`: 1 - `max_views:`: 10 If you are using cURL you can use the `-G` and the `--data-urlencode` flags to encode the query: ``` curl -i -sS -X GET -G "http://localhost:4200/search.json" \ --data-urlencode 'q=wordpress @scossar #fun after:2020-01-01' ``` schema: type: string - name: page in: query example: 1 schema: type: integer responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: posts: type: array items: {} users: type: array items: {} categories: type: array items: {} tags: type: array items: {} groups: type: array items: {} grouped_search_result: type: object additionalProperties: false properties: more_posts: type: - string - 'null' more_users: type: - string - 'null' more_categories: type: - string - 'null' term: type: string search_log_id: type: integer more_full_page_results: type: - string - 'null' can_create_topic: type: boolean error: type: - string - 'null' post_ids: type: array items: {} user_ids: type: array items: {} category_ids: type: array items: {} tag_ids: type: array items: {} group_ids: type: array items: {} required: - more_posts - more_users - more_categories - term - search_log_id - more_full_page_results - can_create_topic - error - post_ids - user_ids - category_ids - tag_ids - group_ids required: - posts - users - categories - tags - groups - grouped_search_result "/site.json": get: summary: Get site info tags: - Site - Categories 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 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 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 - 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 admin_guide: type: integer required: - first_notification - topic_timeline - post_menu - topic_notification_levels - suggested_topics - admin_guide 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' required: - id - name - flair_url - flair_bg_color - flair_color 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 is_custom_flag: type: boolean required: - id - name_key - name - description - short_description - is_flag - is_custom_flag 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 is_custom_flag: type: boolean required: - id - name_key - name - description - short_description - is_flag - is_custom_flag 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: {} wizard_required: type: boolean can_associate_groups: 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' 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 required: - id - name - is_dark 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 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' has_children: type: boolean 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 - has_children - 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 navigation_menu_site_top_tags: 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_dark_color_scheme - censored_regexp - custom_emoji_translation - watched_words_replace - watched_words_link - categories - archetypes - user_fields - auth_providers "/tag_groups.json": get: summary: Get a list of tag groups tags: - Tags operationId: listTagGroups responses: '200': description: tags content: application/json: schema: type: object properties: tag_groups: type: array items: type: object properties: id: type: integer name: type: string tag_names: type: array items: {} parent_tag_name: type: array items: {} one_per_topic: type: boolean permissions: type: object properties: staff: type: integer post: summary: Creates a tag group tags: - Tags operationId: createTagGroup parameters: [] responses: '200': description: tag group created content: application/json: schema: type: object additionalProperties: false properties: tag_group: type: object properties: id: type: integer name: type: string tag_names: type: array items: {} parent_tag_name: type: array items: {} one_per_topic: type: boolean permissions: type: object required: - id - name - tag_names - parent_tag_name - one_per_topic - permissions required: - tag_group requestBody: content: application/json: schema: type: object additionalProperties: false properties: name: type: string required: - name "/tag_groups/{id}.json": get: summary: Get a single tag group tags: - Tags operationId: getTagGroup parameters: - name: id in: path schema: type: string required: true responses: '200': description: notifications content: application/json: schema: type: object properties: tag_group: type: object properties: id: type: integer name: type: string tag_names: type: array items: {} parent_tag_name: type: array items: {} one_per_topic: type: boolean permissions: type: object properties: everyone: type: integer put: summary: Update tag group tags: - Tags operationId: updateTagGroup parameters: - name: id in: path schema: type: string required: true responses: '200': description: Tag group updated content: application/json: schema: type: object properties: success: type: string tag_group: type: object properties: id: type: integer name: type: string tag_names: type: array items: {} parent_tag_name: type: array items: {} one_per_topic: type: boolean permissions: type: object properties: everyone: type: integer requestBody: content: application/json: schema: type: object properties: name: type: string "/tags.json": get: summary: Get a list of tags tags: - Tags operationId: listTags responses: '200': description: notifications content: application/json: schema: type: object properties: tags: type: array items: type: object properties: id: type: string text: type: string count: type: integer pm_count: type: integer target_tag: type: - string - 'null' extras: type: object properties: categories: type: array items: {} "/tag/{name}.json": get: summary: Get a specific tag tags: - Tags operationId: getTag parameters: - name: name in: path schema: type: string required: true responses: '200': description: notifications content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string primary_groups: type: array items: {} topic_list: type: object properties: can_create_topic: type: boolean draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer per_page: type: integer tags: type: array items: type: object properties: id: type: integer name: type: string topic_count: type: integer staff: type: boolean topics: type: array items: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean last_read_post_number: type: integer unread_posts: type: integer pinned: type: boolean unpinned: type: - string - 'null' visible: type: boolean closed: type: boolean archived: type: boolean notification_level: type: integer bookmarked: type: boolean liked: type: boolean tags: type: array items: {} views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: integer pinned_globally: type: boolean featured_link: type: - string - 'null' posters: type: array items: type: object properties: extras: type: string description: type: string user_id: type: integer primary_group_id: type: - string - 'null' "/t/{id}/posts.json": get: summary: Get specific posts from a topic tags: - Topics operationId: getSpecificPostsFromTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: specific posts content: application/json: schema: type: object properties: post_stream: type: object properties: posts: type: array items: type: object properties: id: type: integer name: type: - string - 'null' username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string display_username: type: - string - 'null' primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_wiki: type: boolean read: type: boolean user_title: type: - string - 'null' actions_summary: type: array items: type: object properties: id: type: integer can_act: type: boolean moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: integer reviewable_score_count: type: integer reviewable_score_pending_count: type: integer id: type: integer requestBody: content: application/json: schema: type: object properties: post_ids[]: type: integer required: - post_ids[] "/t/{id}.json": get: summary: Get a single topic tags: - Topics operationId: getTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: specific posts content: application/json: schema: additionalProperties: false properties: post_stream: type: object additionalProperties: false properties: posts: type: array items: type: object additionalProperties: false properties: id: type: integer name: type: string username: type: string avatar_template: type: string created_at: type: string cooked: type: string post_number: type: integer post_type: type: integer updated_at: type: string reply_count: type: integer reply_to_post_number: type: - string - 'null' quote_count: type: integer incoming_link_count: type: integer reads: type: integer readers_count: type: integer score: type: integer yours: type: boolean topic_id: type: integer topic_slug: type: string display_username: type: string primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' version: type: integer can_edit: type: boolean can_delete: type: boolean can_recover: type: boolean can_see_hidden_post: type: boolean can_wiki: type: boolean link_counts: type: array items: type: object additionalProperties: false properties: url: type: string internal: type: boolean reflection: type: boolean title: type: string clicks: type: integer required: - url - internal - reflection - title - clicks read: type: boolean user_title: type: - string - 'null' bookmarked: type: boolean actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer can_act: type: boolean required: - id - can_act moderator: type: boolean admin: type: boolean staff: type: boolean user_id: type: integer hidden: type: boolean trust_level: type: integer deleted_at: type: - string - 'null' user_deleted: type: boolean edit_reason: type: - string - 'null' can_view_edit_history: type: boolean wiki: type: boolean reviewable_id: type: integer reviewable_score_count: type: integer reviewable_score_pending_count: type: integer required: - id - name - username - avatar_template - created_at - cooked - post_number - post_type - updated_at - reply_count - reply_to_post_number - quote_count - incoming_link_count - reads - readers_count - score - yours - topic_id - topic_slug - display_username - primary_group_name - flair_name - flair_url - flair_bg_color - flair_color - version - can_edit - can_delete - can_recover - can_wiki - link_counts - read - user_title - bookmarked - actions_summary - moderator - admin - staff - user_id - hidden - trust_level - deleted_at - user_deleted - edit_reason - can_view_edit_history - wiki - reviewable_id - reviewable_score_count - reviewable_score_pending_count stream: type: array items: {} required: - posts - stream timeline_lookup: type: array items: {} suggested_topics: type: array items: type: object additionalProperties: false properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: - string - 'null' bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean pinned: type: boolean unpinned: type: - string - 'null' excerpt: type: string visible: type: boolean closed: type: boolean archived: type: boolean bookmarked: type: - string - 'null' liked: type: - string - 'null' tags: type: array items: {} tags_descriptions: type: object additionalProperties: false properties: {} like_count: type: integer views: type: integer category_id: type: integer featured_link: type: - string - 'null' posters: type: array items: type: object additionalProperties: false properties: extras: type: string description: type: string user: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template required: - extras - description - user required: - id - title - fancy_title - slug - posts_count - reply_count - highest_post_number - image_url - created_at - last_posted_at - bumped - bumped_at - archetype - unseen - pinned - unpinned - excerpt - visible - closed - archived - bookmarked - liked - tags - tags_descriptions - like_count - views - category_id - featured_link - posters tags: type: array items: {} tags_descriptions: type: object additionalProperties: false properties: {} id: type: integer title: type: string fancy_title: type: string posts_count: type: integer created_at: type: string views: type: integer reply_count: type: integer like_count: type: integer last_posted_at: type: - string - 'null' visible: type: boolean closed: type: boolean archived: type: boolean has_summary: type: boolean archetype: type: string slug: type: string category_id: type: integer word_count: type: - integer - 'null' deleted_at: type: - string - 'null' user_id: type: integer featured_link: type: - string - 'null' pinned_globally: type: boolean pinned_at: type: - string - 'null' pinned_until: type: - string - 'null' image_url: type: - string - 'null' slow_mode_seconds: type: integer draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer unpinned: type: - string - 'null' pinned: type: boolean current_post_number: type: integer highest_post_number: type: - integer - 'null' deleted_by: type: - string - 'null' has_deleted: type: boolean actions_summary: type: array items: type: object additionalProperties: false properties: id: type: integer count: type: integer hidden: type: boolean can_act: type: boolean required: - id - count - hidden - can_act chunk_size: type: integer bookmarked: type: boolean bookmarks: type: array items: {} topic_timer: type: - string - 'null' message_bus_last_id: type: integer participant_count: type: integer show_read_indicator: type: boolean thumbnails: type: - string - 'null' slow_mode_enabled_until: type: - string - 'null' summarizable: type: boolean details: type: object additionalProperties: false properties: can_edit: type: boolean notification_level: type: integer can_move_posts: type: boolean can_delete: type: boolean can_remove_allowed_users: type: boolean can_create_post: type: boolean can_reply_as_new_topic: type: boolean can_invite_to: type: boolean can_invite_via_email: type: boolean can_flag_topic: type: boolean can_convert_topic: type: boolean can_review_topic: type: boolean can_close_topic: type: boolean can_archive_topic: type: boolean can_split_merge_topic: type: boolean can_edit_staff_notes: type: boolean can_toggle_topic_visibility: type: boolean can_pin_unpin_topic: type: boolean can_moderate_category: type: boolean can_remove_self_id: type: integer participants: type: array items: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string post_count: type: integer primary_group_name: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_color: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_group_id: type: - string - 'null' admin: type: boolean moderator: type: boolean trust_level: type: integer required: - id - username - name - avatar_template - post_count - primary_group_name - flair_name - flair_url - flair_color - flair_bg_color - admin - moderator - trust_level created_by: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template last_poster: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template required: - can_edit - notification_level - can_move_posts - can_delete - can_remove_allowed_users - can_create_post - can_reply_as_new_topic - can_convert_topic - can_review_topic - can_close_topic - can_archive_topic - can_split_merge_topic - can_edit_staff_notes - can_toggle_topic_visibility - can_pin_unpin_topic - can_moderate_category - can_remove_self_id - created_by - last_poster required: - post_stream - timeline_lookup - suggested_topics - tags - tags_descriptions - id - title - fancy_title - posts_count - created_at - views - reply_count - like_count - last_posted_at - visible - closed - archived - has_summary - archetype - slug - category_id - word_count - deleted_at - user_id - featured_link - pinned_globally - pinned_at - pinned_until - image_url - slow_mode_seconds - draft - draft_key - draft_sequence - unpinned - pinned - highest_post_number - deleted_by - has_deleted - actions_summary - chunk_size - bookmarked - bookmarks - topic_timer - message_bus_last_id - participant_count - show_read_indicator - thumbnails - slow_mode_enabled_until - summarizable - details delete: summary: Remove a topic tags: - Topics operationId: removeTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: specific posts "/t/-/{id}.json": put: summary: Update a topic tags: - Topics operationId: updateTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: basic_topic: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer requestBody: content: application/json: schema: type: object properties: topic: type: object properties: title: type: string category_id: type: integer "/t/{id}/invite.json": post: summary: Invite to topic tags: - Topics - Invites operationId: inviteToTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: user: type: object properties: id: type: integer username: type: string name: type: string avatar_template: type: string requestBody: content: application/json: schema: type: object properties: user: type: string email: type: string "/t/{id}/bookmark.json": put: summary: Bookmark topic tags: - Topics operationId: bookmarkTopic parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated "/t/{id}/status.json": put: summary: Update the status of a topic tags: - Topics operationId: updateTopicStatus parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: success: type: string example: OK topic_status_update: type: - string - 'null' requestBody: content: application/json: schema: type: object properties: status: type: string enum: - closed - pinned - pinned_globally - archived - visible enabled: type: string enum: - 'true' - 'false' until: type: string description: Only required for `pinned` and `pinned_globally` example: '2030-12-31' required: - status - enabled "/latest.json": get: summary: Get the latest topics tags: - Topics operationId: listLatestTopics parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: order in: query description: 'Enum: `default`, `created`, `activity`, `views`, `posts`, `category`, `likes`, `op_likes`, `posters`' schema: type: string - name: ascending in: query description: Defaults to `desc`, add `ascending=true` to sort asc schema: type: string responses: '200': description: topic updated content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string primary_groups: type: array items: {} topic_list: type: object properties: can_create_topic: type: boolean draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer per_page: type: integer topics: type: array items: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: string created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean last_read_post_number: type: integer unread_posts: type: integer pinned: type: boolean unpinned: type: - string - 'null' visible: type: boolean closed: type: boolean archived: type: boolean notification_level: type: integer bookmarked: type: boolean liked: type: boolean views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: integer op_like_count: type: integer pinned_globally: type: boolean featured_link: type: - string - 'null' posters: type: array items: type: object properties: extras: type: string description: type: string user_id: type: integer primary_group_id: type: - string - 'null' "/top.json": get: summary: Get the top topics filtered by period tags: - Topics operationId: listTopTopics parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: period in: query description: 'Enum: `all`, `yearly`, `quarterly`, `monthly`, `weekly`, `daily`' schema: type: string responses: '200': description: response content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: integer username: type: string name: type: string avatar_template: type: string primary_groups: type: array items: {} topic_list: type: object properties: can_create_topic: type: boolean draft: type: - string - 'null' draft_key: type: string draft_sequence: type: integer for_period: type: string per_page: type: integer topics: type: array items: type: object properties: id: type: integer title: type: string fancy_title: type: string slug: type: string posts_count: type: integer reply_count: type: integer highest_post_number: type: integer image_url: type: - string - 'null' created_at: type: string last_posted_at: type: string bumped: type: boolean bumped_at: type: string archetype: type: string unseen: type: boolean last_read_post_number: type: integer unread_posts: type: integer pinned: type: boolean unpinned: type: boolean visible: type: boolean closed: type: boolean archived: type: boolean notification_level: type: integer bookmarked: type: boolean liked: type: boolean views: type: integer like_count: type: integer has_summary: type: boolean last_poster_username: type: string category_id: type: integer op_like_count: type: integer pinned_globally: type: boolean featured_link: type: - string - 'null' posters: type: array items: type: object properties: extras: type: - string - 'null' description: type: string user_id: type: integer primary_group_id: type: - string - 'null' "/t/{id}/notifications.json": post: summary: Set notification level tags: - Topics operationId: setNotificationLevel parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: success: type: string example: OK requestBody: content: application/json: schema: type: object properties: notification_level: type: string enum: - '0' - '1' - '2' - '3' required: - notification_level "/t/{id}/change-timestamp.json": put: summary: Update topic timestamp tags: - Topics operationId: updateTopicTimestamp parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: success: type: string example: OK requestBody: content: application/json: schema: type: object properties: timestamp: type: string example: '1594291380' required: - timestamp "/t/{id}/timer.json": post: summary: Create topic timer tags: - Topics operationId: createTopicTimer parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: id in: path schema: type: string required: true responses: '200': description: topic updated content: application/json: schema: type: object properties: success: type: string example: OK execute_at: type: string duration: type: - string - 'null' based_on_last_post: type: boolean closed: type: boolean category_id: type: - string - 'null' requestBody: content: application/json: schema: type: object properties: time: type: string example: '' status_type: type: string based_on_last_post: type: boolean category_id: type: integer "/t/external_id/{external_id}.json": get: summary: Get topic by external_id tags: - Topics operationId: getTopicByExternalId parameters: - name: external_id in: path required: true schema: type: string responses: '301': description: redirects to /t/{topic_id}.json "/uploads.json": post: summary: Creates an upload tags: - Uploads operationId: createUpload parameters: [] responses: '200': description: file uploaded content: application/json: schema: additionalProperties: false properties: id: type: integer url: type: string original_filename: type: string filesize: type: integer width: type: integer height: type: integer thumbnail_width: type: integer thumbnail_height: type: integer extension: type: string short_url: type: string short_path: type: string retain_hours: type: - string - 'null' human_filesize: type: string dominant_color: type: - string - 'null' required: - id - url - original_filename - filesize - width - height - thumbnail_width - thumbnail_height - extension - short_url - short_path - retain_hours - human_filesize requestBody: content: multipart/form-data: schema: additionalProperties: false properties: type: type: string enum: - avatar - profile_background - card_background - custom_emoji - composer user_id: type: integer description: required if uploading an avatar synchronous: type: boolean description: Use this flag to return an id and url file: type: string format: binary required: - type "/uploads/generate-presigned-put.json": post: summary: Initiates a direct external upload tags: - Uploads operationId: generatePresignedPut description: |+ Direct external uploads bypass the usual method of creating uploads via the POST /uploads route, and upload directly to an external provider, which by default is S3. This route begins the process, and will return a unique identifier for the external upload as well as a presigned URL which is where the file binary blob should be uploaded to. Once the upload is complete to the external service, you must call the POST /complete-external-upload route using the unique identifier returned by this route, which will create any required Upload record in the Discourse database and also move file from its temporary location to the final destination in the external storage service. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: key: type: string description: The path of the temporary file on the external storage service. example: temp/site/uploads/default/12345/67890.jpg url: type: string description: A presigned PUT URL which must be used to upload the file binary blob to. example: https://file-uploads.s3.us-west-2.amazonaws.com/temp/site/uploads/default/123/456.jpg?x-amz-acl=private&x-amz-meta-sha1-checksum=sha1&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AAAAus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20211221T011246Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=12345678 signed_headers: type: object description: A map of headers that must be sent with the PUT request. example: x-amz-acl: private x-amz-meta-sha1-checksum: sha1 unique_identifier: type: string description: A unique string that identifies the external upload. This must be stored and then sent in the /complete-external-upload endpoint to complete the direct upload. example: 66e86218-80d9-4bda-b4d5-2b6def968705 requestBody: content: application/json: schema: additionalProperties: false properties: type: type: string enum: - avatar - profile_background - card_background - custom_emoji - composer file_name: type: string example: IMG_2021.jpeg file_size: type: integer description: File size should be represented in bytes. example: 4096 metadata: type: object additionalProperties: false properties: sha1-checksum: type: string description: The SHA1 checksum of the upload binary blob. Optionally be provided and serves as an additional security check when later processing the file in complete-external-upload endpoint. required: - type - file_name - file_size "/uploads/complete-external-upload.json": post: summary: Completes a direct external upload tags: - Uploads operationId: completeExternalUpload description: |+ Completes an external upload initialized with /get-presigned-put. The file will be moved from its temporary location in external storage to a final destination in the S3 bucket. An Upload record will also be created in the database in most cases. If a sha1-checksum was provided in the initial request it will also be compared with the uploaded file in storage to make sure the same file was uploaded. The file size will be compared for the same reason. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: id: type: integer url: type: string original_filename: type: string filesize: type: integer width: type: integer height: type: integer thumbnail_width: type: integer thumbnail_height: type: integer extension: type: string short_url: type: string short_path: type: string retain_hours: type: - string - 'null' human_filesize: type: string dominant_color: type: - string - 'null' required: - id - url - original_filename - filesize - width - height - thumbnail_width - thumbnail_height - extension - short_url - short_path - retain_hours - human_filesize requestBody: content: application/json: schema: additionalProperties: false properties: unique_identifier: type: string example: 66e86218-80d9-4bda-b4d5-2b6def968705 description: The unique identifier returned in the original /generate-presigned-put request. for_private_message: type: string example: 'true' description: Optionally set this to true if the upload is for a private message. for_site_setting: type: string example: 'true' description: Optionally set this to true if the upload is for a site setting. pasted: type: string example: 'true' description: Optionally set this to true if the upload was pasted into the upload area. This will convert PNG files to JPEG. required: - unique_identifier "/uploads/create-multipart.json": post: summary: Creates a multipart external upload tags: - Uploads operationId: createMultipartUpload description: |+ Creates a multipart upload in the external storage provider, storing a temporary reference to the external upload similar to /get-presigned-put. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: key: type: string description: The path of the temporary file on the external storage service. example: temp/site/uploads/default/12345/67890.jpg external_upload_identifier: type: string description: The identifier of the multipart upload in the external storage provider. This is the multipart upload_id in AWS S3. example: 84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ unique_identifier: type: string description: A unique string that identifies the external upload. This must be stored and then sent in the /complete-multipart and /batch-presign-multipart-parts endpoints. example: 66e86218-80d9-4bda-b4d5-2b6def968705 required: - external_upload_identifier - key - unique_identifier requestBody: content: application/json: schema: additionalProperties: false properties: upload_type: type: string enum: - avatar - profile_background - card_background - custom_emoji - composer file_name: type: string example: IMG_2021.jpeg file_size: type: integer description: File size should be represented in bytes. example: 4096 metadata: type: object additionalProperties: false properties: sha1-checksum: type: string description: The SHA1 checksum of the upload binary blob. Optionally be provided and serves as an additional security check when later processing the file in complete-external-upload endpoint. required: - upload_type - file_name - file_size "/uploads/batch-presign-multipart-parts.json": post: summary: Generates batches of presigned URLs for multipart parts tags: - Uploads operationId: batchPresignMultipartParts description: |+ Multipart uploads are uploaded in chunks or parts to individual presigned URLs, similar to the one generated by /generate-presigned-put. The part numbers provided must be between 1 and 10000. The total number of parts will depend on the chunk size in bytes that you intend to use to upload each chunk. For example a 12MB file may have 2 5MB chunks and a final 2MB chunk, for part numbers 1, 2, and 3. This endpoint will return a presigned URL for each part number provided, which you can then use to send PUT requests for the binary chunk corresponding to that part. When the part is uploaded, the provider should return an ETag for the part, and this should be stored along with the part number, because this is needed to complete the multipart upload. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: presigned_urls: type: object description: The presigned URLs for each part number, which has the part numbers as keys. example: '1': https://discourse-martin-uploads-test.s3.us-east-2.amazonaws.com/temp/uploads/default/123abc/123abc.jpg?partNumber=1&uploadId=123456abcd&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test&X-Amz-Date=20211222T012336Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123 required: - presigned_urls requestBody: content: application/json: schema: additionalProperties: false properties: part_numbers: type: array description: The part numbers to generate the presigned URLs for, must be between 1 and 10000. example: - 1 - 2 - 3 unique_identifier: type: string description: The unique identifier returned in the original /create-multipart request. example: 66e86218-80d9-4bda-b4d5-2b6def968705 required: - part_numbers - unique_identifier "/uploads/abort-multipart.json": post: summary: Abort multipart upload tags: - Uploads operationId: abortMultipart description: |+ This endpoint aborts the multipart upload initiated with /create-multipart. This should be used when cancelling the upload. It does not matter if parts were already uploaded into the external storage provider. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success requestBody: content: application/json: schema: additionalProperties: false properties: external_upload_identifier: type: string description: The identifier of the multipart upload in the external storage provider. This is the multipart upload_id in AWS S3. example: 84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ required: - external_upload_identifier "/uploads/complete-multipart.json": post: summary: Complete multipart upload tags: - Uploads operationId: completeMultipart description: |+ Completes the multipart upload in the external store, and copies the file from its temporary location to its final location in the store. All of the parts must have been uploaded to the external storage provider. An Upload record will be completed in most cases once the file is copied to its final location. You must have the correct permissions and CORS settings configured in your external provider. We support AWS S3 as the default. See: https://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4. An external file store must be set up and `enable_direct_s3_uploads` must be set to true for this endpoint to function. parameters: [] responses: '200': description: external upload initialized content: application/json: schema: additionalProperties: false properties: id: type: integer url: type: string original_filename: type: string filesize: type: integer width: type: integer height: type: integer thumbnail_width: type: integer thumbnail_height: type: integer extension: type: string short_url: type: string short_path: type: string retain_hours: type: - string - 'null' human_filesize: type: string dominant_color: type: - string - 'null' required: - id - url - original_filename - filesize - width - height - thumbnail_width - thumbnail_height - extension - short_url - short_path - retain_hours - human_filesize requestBody: content: application/json: schema: additionalProperties: false properties: unique_identifier: type: string example: 66e86218-80d9-4bda-b4d5-2b6def968705 description: The unique identifier returned in the original /create-multipart request. parts: type: array example: - part_number: 1 etag: 0c376dcfcc2606f4335bbc732de93344 - part_number: 2 etag: '09ert8cfcc2606f4335bbc732de91122' description: All of the part numbers and their corresponding ETags that have been uploaded must be provided. required: - unique_identifier - parts "/user-badges/{username}.json": get: summary: List badges for a user tags: - Badges - Users 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 "/users.json": post: summary: Creates a user tags: - Users operationId: createUser parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string responses: '200': description: user created content: application/json: schema: additionalProperties: false properties: success: type: boolean active: type: boolean message: type: string user_id: type: integer required: - success - active - message requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string email: type: string password: type: string username: type: string active: type: boolean description: This param requires an api key in the request header or it will be ignored approved: type: boolean user_fields[1]: type: boolean external_ids: type: object required: - name - email - password - username "/u/{username}.json": get: summary: Get a single user by username tags: - Users operationId: getUser parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: username in: path required: true schema: type: string responses: '200': description: user response content: application/json: schema: additionalProperties: false properties: user_badges: type: array items: {} user: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string last_posted_at: type: - string - 'null' last_seen_at: type: - string - 'null' created_at: type: string ignored: type: boolean muted: type: boolean can_ignore_user: type: boolean can_mute_user: type: boolean can_send_private_messages: type: boolean can_send_private_message_to_user: type: boolean trust_level: type: integer moderator: type: boolean admin: type: boolean title: type: - string - 'null' badge_count: type: integer second_factor_backup_enabled: type: boolean user_fields: type: object additionalProperties: false properties: '1': type: - string - 'null' '2': type: - string - 'null' required: - '1' - '2' custom_fields: type: object additionalProperties: false properties: first_name: type: - string - 'null' time_read: type: integer recent_time_read: type: integer primary_group_id: type: - string - 'null' primary_group_name: type: - string - 'null' flair_group_id: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' featured_topic: type: - string - 'null' staged: type: boolean can_edit: type: boolean can_edit_username: type: boolean can_edit_email: type: boolean can_edit_name: type: boolean uploaded_avatar_id: type: - string - 'null' has_title_badges: type: boolean pending_count: type: integer pending_posts_count: type: integer profile_view_count: type: integer second_factor_enabled: type: boolean can_upload_profile_header: type: boolean can_upload_user_card_background: type: boolean post_count: type: integer can_be_deleted: type: boolean can_delete_all_posts: type: boolean locale: type: - string - 'null' muted_category_ids: type: array items: {} regular_category_ids: type: array items: {} watched_tags: type: array items: {} watching_first_post_tags: type: array items: {} tracked_tags: type: array items: {} muted_tags: type: array items: {} tracked_category_ids: type: array items: {} watched_category_ids: type: array items: {} watched_first_post_category_ids: type: array items: {} system_avatar_upload_id: type: - string - 'null' system_avatar_template: type: string muted_usernames: type: array items: {} ignored_usernames: type: array items: {} allowed_pm_usernames: type: array items: {} mailing_list_posts_per_day: type: integer can_change_bio: type: boolean can_change_location: type: boolean can_change_website: type: boolean can_change_tracking_preferences: type: boolean user_api_keys: type: - string - 'null' sidebar_tags: type: array sidebar_category_ids: type: array display_sidebar_tags: type: boolean user_auth_tokens: type: array items: type: object additionalProperties: false properties: id: type: integer client_ip: type: string location: type: string browser: type: string device: type: string os: type: string icon: type: string created_at: type: string seen_at: type: string is_active: type: boolean required: - id - client_ip - location - browser - device - os - icon - created_at - seen_at - is_active user_notification_schedule: type: object additionalProperties: false properties: enabled: type: boolean day_0_start_time: type: integer day_0_end_time: type: integer day_1_start_time: type: integer day_1_end_time: type: integer day_2_start_time: type: integer day_2_end_time: type: integer day_3_start_time: type: integer day_3_end_time: type: integer day_4_start_time: type: integer day_4_end_time: type: integer day_5_start_time: type: integer day_5_end_time: type: integer day_6_start_time: type: integer day_6_end_time: type: integer required: - enabled - day_0_start_time - day_0_end_time - day_1_start_time - day_1_end_time - day_2_start_time - day_2_end_time - day_3_start_time - day_3_end_time - day_4_start_time - day_4_end_time - day_5_start_time - day_5_end_time - day_6_start_time - day_6_end_time use_logo_small_as_avatar: type: boolean featured_user_badge_ids: type: array items: {} invited_by: type: - string - 'null' groups: type: array items: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string display_name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - display_name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state group_users: type: array items: type: object additionalProperties: false properties: group_id: type: integer user_id: type: integer notification_level: type: integer owner: type: boolean required: - group_id - user_id - notification_level user_option: type: object additionalProperties: false properties: user_id: type: integer mailing_list_mode: type: boolean mailing_list_mode_frequency: type: integer email_digests: type: boolean email_level: type: integer email_messages_level: type: integer external_links_in_new_tab: type: boolean bookmark_auto_delete_preference: type: integer color_scheme_id: type: - string - 'null' dark_scheme_id: type: - string - 'null' dynamic_favicon: type: boolean enable_quoting: type: boolean enable_defer: type: boolean digest_after_minutes: type: integer automatically_unpin_topics: type: boolean auto_track_topics_after_msecs: type: integer notification_level_when_replying: type: integer new_topic_duration_minutes: type: integer email_previous_replies: type: integer email_in_reply_to: type: boolean like_notification_frequency: type: integer include_tl0_in_digests: type: boolean theme_ids: type: array items: {} theme_key_seq: type: integer allow_private_messages: type: boolean enable_allowed_pm_users: type: boolean homepage_id: type: - string - 'null' hide_profile_and_presence: type: boolean text_size: type: string text_size_seq: type: integer title_count_mode: type: string timezone: type: - string - 'null' skip_new_user_tips: type: boolean default_calendar: type: string oldest_search_log_date: type: - string - 'null' sidebar_link_to_filtered_list: type: boolean sidebar_show_count_of_new_items: type: boolean watched_precedence_over_muted: type: - boolean - 'null' seen_popups: type: - array - 'null' required: - user_id - mailing_list_mode - mailing_list_mode_frequency - email_digests - email_level - email_messages_level - external_links_in_new_tab - color_scheme_id - dark_scheme_id - dynamic_favicon - enable_quoting - enable_defer - digest_after_minutes - automatically_unpin_topics - auto_track_topics_after_msecs - notification_level_when_replying - new_topic_duration_minutes - email_previous_replies - email_in_reply_to - like_notification_frequency - include_tl0_in_digests - theme_ids - theme_key_seq - allow_private_messages - enable_allowed_pm_users - homepage_id - hide_profile_and_presence - text_size - text_size_seq - title_count_mode - timezone - skip_new_user_tips required: - id - username - name - avatar_template - last_posted_at - last_seen_at - created_at - ignored - muted - can_ignore_user - can_mute_user - can_send_private_messages - can_send_private_message_to_user - trust_level - moderator - admin - title - badge_count - custom_fields - time_read - recent_time_read - primary_group_id - primary_group_name - flair_group_id - flair_name - flair_url - flair_bg_color - flair_color - featured_topic - staged - can_edit - can_edit_username - can_edit_email - can_edit_name - uploaded_avatar_id - has_title_badges - pending_count - profile_view_count - second_factor_enabled - can_upload_profile_header - can_upload_user_card_background - post_count - can_be_deleted - can_delete_all_posts - locale - muted_category_ids - regular_category_ids - watched_tags - watching_first_post_tags - tracked_tags - muted_tags - tracked_category_ids - watched_category_ids - watched_first_post_category_ids - system_avatar_upload_id - system_avatar_template - muted_usernames - ignored_usernames - allowed_pm_usernames - mailing_list_posts_per_day - can_change_bio - can_change_location - can_change_website - can_change_tracking_preferences - user_api_keys - user_auth_tokens - user_notification_schedule - use_logo_small_as_avatar - featured_user_badge_ids - invited_by - groups - group_users - user_option required: - user_badges - user put: summary: Update a user tags: - Users operationId: updateUser parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: username in: path required: true schema: type: string responses: '200': description: user updated content: application/json: schema: additionalProperties: false properties: success: type: string user: type: object required: - success - user requestBody: content: application/json: schema: additionalProperties: false properties: name: type: string external_ids: type: object "/u/by-external/{external_id}.json": get: summary: Get a user by external_id tags: - Users operationId: getUserExternalId parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: external_id in: path required: true schema: type: string responses: '200': description: user response content: application/json: schema: additionalProperties: false properties: user_badges: type: array items: {} user: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string last_posted_at: type: - string - 'null' last_seen_at: type: - string - 'null' created_at: type: string ignored: type: boolean muted: type: boolean can_ignore_user: type: boolean can_mute_user: type: boolean can_send_private_messages: type: boolean can_send_private_message_to_user: type: boolean trust_level: type: integer moderator: type: boolean admin: type: boolean title: type: - string - 'null' badge_count: type: integer second_factor_backup_enabled: type: boolean user_fields: type: object additionalProperties: false properties: '1': type: - string - 'null' '2': type: - string - 'null' required: - '1' - '2' custom_fields: type: object additionalProperties: false properties: first_name: type: - string - 'null' time_read: type: integer recent_time_read: type: integer primary_group_id: type: - string - 'null' primary_group_name: type: - string - 'null' flair_group_id: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' featured_topic: type: - string - 'null' staged: type: boolean can_edit: type: boolean can_edit_username: type: boolean can_edit_email: type: boolean can_edit_name: type: boolean uploaded_avatar_id: type: - string - 'null' has_title_badges: type: boolean pending_count: type: integer pending_posts_count: type: integer profile_view_count: type: integer second_factor_enabled: type: boolean can_upload_profile_header: type: boolean can_upload_user_card_background: type: boolean post_count: type: integer can_be_deleted: type: boolean can_delete_all_posts: type: boolean locale: type: - string - 'null' muted_category_ids: type: array items: {} regular_category_ids: type: array items: {} watched_tags: type: array items: {} watching_first_post_tags: type: array items: {} tracked_tags: type: array items: {} muted_tags: type: array items: {} tracked_category_ids: type: array items: {} watched_category_ids: type: array items: {} watched_first_post_category_ids: type: array items: {} system_avatar_upload_id: type: - string - 'null' system_avatar_template: type: string muted_usernames: type: array items: {} ignored_usernames: type: array items: {} allowed_pm_usernames: type: array items: {} mailing_list_posts_per_day: type: integer can_change_bio: type: boolean can_change_location: type: boolean can_change_website: type: boolean can_change_tracking_preferences: type: boolean user_api_keys: type: - string - 'null' sidebar_tags: type: array sidebar_category_ids: type: array display_sidebar_tags: type: boolean user_auth_tokens: type: array items: type: object additionalProperties: false properties: id: type: integer client_ip: type: string location: type: string browser: type: string device: type: string os: type: string icon: type: string created_at: type: string seen_at: type: string is_active: type: boolean required: - id - client_ip - location - browser - device - os - icon - created_at - seen_at - is_active user_notification_schedule: type: object additionalProperties: false properties: enabled: type: boolean day_0_start_time: type: integer day_0_end_time: type: integer day_1_start_time: type: integer day_1_end_time: type: integer day_2_start_time: type: integer day_2_end_time: type: integer day_3_start_time: type: integer day_3_end_time: type: integer day_4_start_time: type: integer day_4_end_time: type: integer day_5_start_time: type: integer day_5_end_time: type: integer day_6_start_time: type: integer day_6_end_time: type: integer required: - enabled - day_0_start_time - day_0_end_time - day_1_start_time - day_1_end_time - day_2_start_time - day_2_end_time - day_3_start_time - day_3_end_time - day_4_start_time - day_4_end_time - day_5_start_time - day_5_end_time - day_6_start_time - day_6_end_time use_logo_small_as_avatar: type: boolean featured_user_badge_ids: type: array items: {} invited_by: type: - string - 'null' groups: type: array items: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string display_name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - display_name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state group_users: type: array items: type: object additionalProperties: false properties: group_id: type: integer user_id: type: integer notification_level: type: integer owner: type: boolean required: - group_id - user_id - notification_level user_option: type: object additionalProperties: false properties: user_id: type: integer mailing_list_mode: type: boolean mailing_list_mode_frequency: type: integer email_digests: type: boolean email_level: type: integer email_messages_level: type: integer external_links_in_new_tab: type: boolean bookmark_auto_delete_preference: type: integer color_scheme_id: type: - string - 'null' dark_scheme_id: type: - string - 'null' dynamic_favicon: type: boolean enable_quoting: type: boolean enable_defer: type: boolean digest_after_minutes: type: integer automatically_unpin_topics: type: boolean auto_track_topics_after_msecs: type: integer notification_level_when_replying: type: integer new_topic_duration_minutes: type: integer email_previous_replies: type: integer email_in_reply_to: type: boolean like_notification_frequency: type: integer include_tl0_in_digests: type: boolean theme_ids: type: array items: {} theme_key_seq: type: integer allow_private_messages: type: boolean enable_allowed_pm_users: type: boolean homepage_id: type: - string - 'null' hide_profile_and_presence: type: boolean text_size: type: string text_size_seq: type: integer title_count_mode: type: string timezone: type: - string - 'null' skip_new_user_tips: type: boolean default_calendar: type: string oldest_search_log_date: type: - string - 'null' sidebar_link_to_filtered_list: type: boolean sidebar_show_count_of_new_items: type: boolean watched_precedence_over_muted: type: - boolean - 'null' seen_popups: type: - array - 'null' required: - user_id - mailing_list_mode - mailing_list_mode_frequency - email_digests - email_level - email_messages_level - external_links_in_new_tab - color_scheme_id - dark_scheme_id - dynamic_favicon - enable_quoting - enable_defer - digest_after_minutes - automatically_unpin_topics - auto_track_topics_after_msecs - notification_level_when_replying - new_topic_duration_minutes - email_previous_replies - email_in_reply_to - like_notification_frequency - include_tl0_in_digests - theme_ids - theme_key_seq - allow_private_messages - enable_allowed_pm_users - homepage_id - hide_profile_and_presence - text_size - text_size_seq - title_count_mode - timezone - skip_new_user_tips required: - id - username - name - avatar_template - last_posted_at - last_seen_at - created_at - ignored - muted - can_ignore_user - can_mute_user - can_send_private_messages - can_send_private_message_to_user - trust_level - moderator - admin - title - badge_count - custom_fields - time_read - recent_time_read - primary_group_id - primary_group_name - flair_group_id - flair_name - flair_url - flair_bg_color - flair_color - featured_topic - staged - can_edit - can_edit_username - can_edit_email - can_edit_name - uploaded_avatar_id - has_title_badges - pending_count - profile_view_count - second_factor_enabled - can_upload_profile_header - can_upload_user_card_background - post_count - can_be_deleted - can_delete_all_posts - locale - muted_category_ids - regular_category_ids - watched_tags - watching_first_post_tags - tracked_tags - muted_tags - tracked_category_ids - watched_category_ids - watched_first_post_category_ids - system_avatar_upload_id - system_avatar_template - muted_usernames - ignored_usernames - allowed_pm_usernames - mailing_list_posts_per_day - can_change_bio - can_change_location - can_change_website - can_change_tracking_preferences - user_api_keys - user_auth_tokens - user_notification_schedule - use_logo_small_as_avatar - featured_user_badge_ids - invited_by - groups - group_users - user_option required: - user_badges - user "/u/by-external/{provider}/{external_id}.json": get: summary: Get a user by identity provider external ID tags: - Users operationId: getUserIdentiyProviderExternalId parameters: - name: Api-Key in: header required: true schema: type: string - name: Api-Username in: header required: true schema: type: string - name: provider in: path required: true description: 'Authentication provider name. Can be found in the provider callback URL: `/auth/{provider}/callback`' schema: type: string - name: external_id in: path required: true schema: type: string responses: '200': description: user response content: application/json: schema: additionalProperties: false properties: user_badges: type: array items: {} user: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string last_posted_at: type: - string - 'null' last_seen_at: type: - string - 'null' created_at: type: string ignored: type: boolean muted: type: boolean can_ignore_user: type: boolean can_mute_user: type: boolean can_send_private_messages: type: boolean can_send_private_message_to_user: type: boolean trust_level: type: integer moderator: type: boolean admin: type: boolean title: type: - string - 'null' badge_count: type: integer second_factor_backup_enabled: type: boolean user_fields: type: object additionalProperties: false properties: '1': type: - string - 'null' '2': type: - string - 'null' required: - '1' - '2' custom_fields: type: object additionalProperties: false properties: first_name: type: - string - 'null' time_read: type: integer recent_time_read: type: integer primary_group_id: type: - string - 'null' primary_group_name: type: - string - 'null' flair_group_id: type: - string - 'null' flair_name: type: - string - 'null' flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' featured_topic: type: - string - 'null' staged: type: boolean can_edit: type: boolean can_edit_username: type: boolean can_edit_email: type: boolean can_edit_name: type: boolean uploaded_avatar_id: type: - string - 'null' has_title_badges: type: boolean pending_count: type: integer pending_posts_count: type: integer profile_view_count: type: integer second_factor_enabled: type: boolean can_upload_profile_header: type: boolean can_upload_user_card_background: type: boolean post_count: type: integer can_be_deleted: type: boolean can_delete_all_posts: type: boolean locale: type: - string - 'null' muted_category_ids: type: array items: {} regular_category_ids: type: array items: {} watched_tags: type: array items: {} watching_first_post_tags: type: array items: {} tracked_tags: type: array items: {} muted_tags: type: array items: {} tracked_category_ids: type: array items: {} watched_category_ids: type: array items: {} watched_first_post_category_ids: type: array items: {} system_avatar_upload_id: type: - string - 'null' system_avatar_template: type: string muted_usernames: type: array items: {} ignored_usernames: type: array items: {} allowed_pm_usernames: type: array items: {} mailing_list_posts_per_day: type: integer can_change_bio: type: boolean can_change_location: type: boolean can_change_website: type: boolean can_change_tracking_preferences: type: boolean user_api_keys: type: - string - 'null' sidebar_tags: type: array sidebar_category_ids: type: array display_sidebar_tags: type: boolean user_auth_tokens: type: array items: type: object additionalProperties: false properties: id: type: integer client_ip: type: string location: type: string browser: type: string device: type: string os: type: string icon: type: string created_at: type: string seen_at: type: string is_active: type: boolean required: - id - client_ip - location - browser - device - os - icon - created_at - seen_at - is_active user_notification_schedule: type: object additionalProperties: false properties: enabled: type: boolean day_0_start_time: type: integer day_0_end_time: type: integer day_1_start_time: type: integer day_1_end_time: type: integer day_2_start_time: type: integer day_2_end_time: type: integer day_3_start_time: type: integer day_3_end_time: type: integer day_4_start_time: type: integer day_4_end_time: type: integer day_5_start_time: type: integer day_5_end_time: type: integer day_6_start_time: type: integer day_6_end_time: type: integer required: - enabled - day_0_start_time - day_0_end_time - day_1_start_time - day_1_end_time - day_2_start_time - day_2_end_time - day_3_start_time - day_3_end_time - day_4_start_time - day_4_end_time - day_5_start_time - day_5_end_time - day_6_start_time - day_6_end_time use_logo_small_as_avatar: type: boolean featured_user_badge_ids: type: array items: {} invited_by: type: - string - 'null' groups: type: array items: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string display_name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - display_name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state group_users: type: array items: type: object additionalProperties: false properties: group_id: type: integer user_id: type: integer notification_level: type: integer owner: type: boolean required: - group_id - user_id - notification_level user_option: type: object additionalProperties: false properties: user_id: type: integer mailing_list_mode: type: boolean mailing_list_mode_frequency: type: integer email_digests: type: boolean email_level: type: integer email_messages_level: type: integer external_links_in_new_tab: type: boolean bookmark_auto_delete_preference: type: integer color_scheme_id: type: - string - 'null' dark_scheme_id: type: - string - 'null' dynamic_favicon: type: boolean enable_quoting: type: boolean enable_defer: type: boolean digest_after_minutes: type: integer automatically_unpin_topics: type: boolean auto_track_topics_after_msecs: type: integer notification_level_when_replying: type: integer new_topic_duration_minutes: type: integer email_previous_replies: type: integer email_in_reply_to: type: boolean like_notification_frequency: type: integer include_tl0_in_digests: type: boolean theme_ids: type: array items: {} theme_key_seq: type: integer allow_private_messages: type: boolean enable_allowed_pm_users: type: boolean homepage_id: type: - string - 'null' hide_profile_and_presence: type: boolean text_size: type: string text_size_seq: type: integer title_count_mode: type: string timezone: type: - string - 'null' skip_new_user_tips: type: boolean default_calendar: type: string oldest_search_log_date: type: - string - 'null' sidebar_link_to_filtered_list: type: boolean sidebar_show_count_of_new_items: type: boolean watched_precedence_over_muted: type: - boolean - 'null' seen_popups: type: - array - 'null' required: - user_id - mailing_list_mode - mailing_list_mode_frequency - email_digests - email_level - email_messages_level - external_links_in_new_tab - color_scheme_id - dark_scheme_id - dynamic_favicon - enable_quoting - enable_defer - digest_after_minutes - automatically_unpin_topics - auto_track_topics_after_msecs - notification_level_when_replying - new_topic_duration_minutes - email_previous_replies - email_in_reply_to - like_notification_frequency - include_tl0_in_digests - theme_ids - theme_key_seq - allow_private_messages - enable_allowed_pm_users - homepage_id - hide_profile_and_presence - text_size - text_size_seq - title_count_mode - timezone - skip_new_user_tips required: - id - username - name - avatar_template - last_posted_at - last_seen_at - created_at - ignored - muted - can_ignore_user - can_mute_user - can_send_private_messages - can_send_private_message_to_user - trust_level - moderator - admin - title - badge_count - custom_fields - time_read - recent_time_read - primary_group_id - primary_group_name - flair_group_id - flair_name - flair_url - flair_bg_color - flair_color - featured_topic - staged - can_edit - can_edit_username - can_edit_email - can_edit_name - uploaded_avatar_id - has_title_badges - pending_count - profile_view_count - second_factor_enabled - can_upload_profile_header - can_upload_user_card_background - post_count - can_be_deleted - can_delete_all_posts - locale - muted_category_ids - regular_category_ids - watched_tags - watching_first_post_tags - tracked_tags - muted_tags - tracked_category_ids - watched_category_ids - watched_first_post_category_ids - system_avatar_upload_id - system_avatar_template - muted_usernames - ignored_usernames - allowed_pm_usernames - mailing_list_posts_per_day - can_change_bio - can_change_location - can_change_website - can_change_tracking_preferences - user_api_keys - user_auth_tokens - user_notification_schedule - use_logo_small_as_avatar - featured_user_badge_ids - invited_by - groups - group_users - user_option required: - user_badges - user "/u/{username}/preferences/avatar/pick.json": put: summary: Update avatar tags: - Users operationId: updateAvatar parameters: - name: username in: path required: true schema: type: string responses: '200': description: avatar updated content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success requestBody: content: application/json: schema: additionalProperties: false properties: upload_id: type: integer type: type: string enum: - uploaded - custom - gravatar - system required: - upload_id - type "/u/{username}/preferences/email.json": put: summary: Update email tags: - Users operationId: updateEmail parameters: - name: username in: path required: true schema: type: string responses: '200': description: email updated requestBody: content: application/json: schema: additionalProperties: false properties: email: type: string format: email required: - email "/u/{username}/preferences/username.json": put: summary: Update username tags: - Users operationId: updateUsername parameters: - name: username in: path required: true schema: type: string responses: '200': description: username updated requestBody: content: application/json: schema: additionalProperties: false properties: new_username: type: string required: - new_username "/directory_items.json": get: summary: Get a public list of users tags: - Users operationId: listUsersPublic parameters: - name: period in: query schema: type: string enum: - daily - weekly - monthly - quarterly - yearly - all required: true - name: order in: query schema: type: string enum: - likes_received - likes_given - topic_count - post_count - topics_entered - posts_read - days_visited required: true - name: asc in: query schema: type: string enum: - 'true' - name: page in: query schema: type: integer responses: '200': description: directory items response content: application/json: schema: additionalProperties: false properties: directory_items: type: array items: type: object additionalProperties: false properties: id: type: integer likes_received: type: integer likes_given: type: integer topics_entered: type: integer topic_count: type: integer post_count: type: integer posts_read: type: integer days_visited: type: integer user: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string title: type: - string - 'null' required: - id - username - name - avatar_template - title required: - id - likes_received - likes_given - topics_entered - topic_count - post_count - posts_read - days_visited - user meta: type: object additionalProperties: false properties: last_updated_at: type: - string - 'null' total_rows_directory_items: type: integer load_more_directory_items: type: string required: - last_updated_at - total_rows_directory_items - load_more_directory_items required: - directory_items - meta "/admin/users/{id}.json": get: summary: Get a user by id tags: - Users - Admin operationId: adminGetUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string active: type: boolean admin: type: boolean moderator: type: boolean last_seen_at: type: - string - 'null' last_emailed_at: type: - string - 'null' created_at: type: string last_seen_age: type: - number - 'null' last_emailed_age: type: - number - 'null' created_at_age: type: - number - 'null' trust_level: type: integer manual_locked_trust_level: type: - string - 'null' title: type: - string - 'null' time_read: type: integer staged: type: boolean days_visited: type: integer posts_read_count: type: integer topics_entered: type: integer post_count: type: integer associated_accounts: type: array items: {} can_send_activation_email: type: boolean can_activate: type: boolean can_deactivate: type: boolean ip_address: type: string registration_ip_address: type: - string - 'null' can_grant_admin: type: boolean can_revoke_admin: type: boolean can_grant_moderation: type: boolean can_revoke_moderation: type: boolean can_impersonate: type: boolean like_count: type: integer like_given_count: type: integer topic_count: type: integer flags_given_count: type: integer flags_received_count: type: integer private_topics_count: type: integer can_delete_all_posts: type: boolean can_be_deleted: type: boolean can_be_anonymized: type: boolean can_be_merged: type: boolean full_suspend_reason: type: - string - 'null' silence_reason: type: - string - 'null' post_edits_count: type: - integer - 'null' primary_group_id: type: - string - 'null' badge_count: type: integer warnings_received_count: type: integer bounce_score: type: - integer - 'null' reset_bounce_score_after: type: - string - 'null' can_view_action_logs: type: boolean can_disable_second_factor: type: boolean can_delete_sso_record: type: boolean api_key_count: type: integer single_sign_on_record: type: - string - 'null' approved_by: type: - object - 'null' additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template suspended_by: type: - string - 'null' silenced_by: type: - string - 'null' penalty_counts: type: object additionalProperties: false properties: silenced: type: integer suspended: type: integer required: - silenced - suspended next_penalty: type: string tl3_requirements: type: object additionalProperties: false properties: time_period: type: integer requirements_met: type: boolean requirements_lost: type: boolean trust_level_locked: type: boolean on_grace_period: type: boolean days_visited: type: integer min_days_visited: type: integer num_topics_replied_to: type: integer min_topics_replied_to: type: integer topics_viewed: type: integer min_topics_viewed: type: integer posts_read: type: integer min_posts_read: type: integer topics_viewed_all_time: type: integer min_topics_viewed_all_time: type: integer posts_read_all_time: type: integer min_posts_read_all_time: type: integer num_flagged_posts: type: integer max_flagged_posts: type: integer num_flagged_by_users: type: integer max_flagged_by_users: type: integer num_likes_given: type: integer min_likes_given: type: integer num_likes_received: type: integer min_likes_received: type: integer num_likes_received_days: type: integer min_likes_received_days: type: integer num_likes_received_users: type: integer min_likes_received_users: type: integer penalty_counts: type: object additionalProperties: false properties: silenced: type: integer suspended: type: integer total: type: integer required: - silenced - suspended - total required: - time_period - requirements_met - requirements_lost - trust_level_locked - on_grace_period - days_visited - min_days_visited - num_topics_replied_to - min_topics_replied_to - topics_viewed - min_topics_viewed - posts_read - min_posts_read - topics_viewed_all_time - min_topics_viewed_all_time - posts_read_all_time - min_posts_read_all_time - num_flagged_posts - max_flagged_posts - num_flagged_by_users - max_flagged_by_users - num_likes_given - min_likes_given - num_likes_received - min_likes_received - num_likes_received_days - min_likes_received_days - num_likes_received_users - min_likes_received_users - penalty_counts groups: type: array items: type: object additionalProperties: false properties: id: type: integer automatic: type: boolean name: type: string display_name: type: string user_count: type: integer mentionable_level: type: integer messageable_level: type: integer visibility_level: type: integer primary_group: type: boolean title: type: - string - 'null' grant_trust_level: type: - string - 'null' incoming_email: type: - string - 'null' has_messages: type: boolean flair_url: type: - string - 'null' flair_bg_color: type: - string - 'null' flair_color: type: - string - 'null' flair_group_id: type: - string - 'null' bio_raw: type: - string - 'null' bio_cooked: type: - string - 'null' bio_excerpt: type: - string - 'null' public_admission: type: boolean public_exit: type: boolean allow_membership_requests: type: boolean full_name: type: - string - 'null' default_notification_level: type: integer membership_request_template: type: - string - 'null' members_visibility_level: type: integer can_see_members: type: boolean can_admin_group: type: boolean publish_read_state: type: boolean required: - id - automatic - name - display_name - user_count - mentionable_level - messageable_level - visibility_level - primary_group - title - grant_trust_level - incoming_email - has_messages - flair_url - flair_bg_color - flair_color - bio_raw - bio_cooked - bio_excerpt - public_admission - public_exit - allow_membership_requests - full_name - default_notification_level - membership_request_template - members_visibility_level - can_see_members - can_admin_group - publish_read_state external_ids: type: object required: - id - username - name - avatar_template - active - admin - moderator - last_seen_at - last_emailed_at - created_at - last_seen_age - last_emailed_age - created_at_age - trust_level - manual_locked_trust_level - title - time_read - staged - days_visited - posts_read_count - topics_entered - post_count - can_send_activation_email - can_activate - can_deactivate - ip_address - registration_ip_address - can_grant_admin - can_revoke_admin - can_grant_moderation - can_revoke_moderation - can_impersonate - like_count - like_given_count - topic_count - flags_given_count - flags_received_count - private_topics_count - can_delete_all_posts - can_be_deleted - can_be_anonymized - can_be_merged - full_suspend_reason - silence_reason - primary_group_id - badge_count - warnings_received_count - bounce_score - reset_bounce_score_after - can_view_action_logs - can_disable_second_factor - can_delete_sso_record - api_key_count - single_sign_on_record - approved_by - suspended_by - silenced_by - groups - external_ids delete: summary: Delete a user tags: - Users - Admin operationId: deleteUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: deleted: type: boolean required: - deleted requestBody: content: application/json: schema: additionalProperties: false properties: delete_posts: type: boolean block_email: type: boolean block_urls: type: boolean block_ip: type: boolean "/admin/users/{id}/activate.json": put: summary: Activate a user tags: - Users - Admin operationId: activateUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success "/admin/users/{id}/deactivate.json": put: summary: Deactivate a user tags: - Users - Admin operationId: deactivateUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success "/admin/users/{id}/suspend.json": put: summary: Suspend a user tags: - Users - Admin operationId: suspendUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: suspension: type: object additionalProperties: false properties: suspend_reason: type: string full_suspend_reason: type: string suspended_till: type: string suspended_at: type: string suspended_by: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template required: - suspend_reason - full_suspend_reason - suspended_till - suspended_at - suspended_by required: - suspension requestBody: content: application/json: schema: additionalProperties: false properties: suspend_until: type: string example: '2121-02-22' reason: type: string message: type: string description: Will send an email with this message when present post_action: type: string example: delete required: - suspend_until - reason "/admin/users/{id}/silence.json": put: summary: Silence a user tags: - Users - Admin operationId: silenceUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: silence: type: object additionalProperties: false properties: silenced: type: boolean silence_reason: type: string silenced_till: type: string silenced_at: type: string silenced_by: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string avatar_template: type: string required: - id - username - name - avatar_template required: - silenced - silence_reason - silenced_till - silenced_at - silenced_by required: - silence requestBody: content: application/json: schema: additionalProperties: false properties: silenced_till: type: string example: '2022-06-01T08:00:00.000Z' reason: type: string message: type: string description: Will send an email with this message when present post_action: type: string example: delete "/admin/users/{id}/anonymize.json": put: summary: Anonymize a user tags: - Users - Admin operationId: anonymizeUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: success: type: string username: type: string required: - success - username "/admin/users/{id}/log_out.json": post: summary: Log a user out tags: - Users - Admin operationId: logOutUser parameters: - name: id in: path required: true schema: type: integer responses: '200': description: response content: application/json: schema: additionalProperties: false properties: success: type: string example: OK required: - success "/user_avatar/{username}/refresh_gravatar.json": post: summary: Refresh gravatar tags: - Users - Admin operationId: refreshGravatar parameters: - name: username in: path required: true schema: type: string responses: '200': description: response content: application/json: schema: additionalProperties: false properties: gravatar_upload_id: type: - integer - 'null' gravatar_avatar_template: type: - string - 'null' required: - gravatar_upload_id - gravatar_avatar_template "/admin/users/list/{flag}.json": get: summary: Get a list of users tags: - Users - Admin operationId: adminListUsers parameters: - name: flag in: path schema: type: string enum: - active - new - staff - suspended - blocked - suspect required: true - name: order in: query schema: type: string enum: - created - last_emailed - seen - username - email - trust_level - days_visited - posts_read - topics_viewed - posts - read_time - name: asc in: query schema: type: string enum: - 'true' - name: page in: query schema: type: integer - name: show_emails in: query description: Include user email addresses in response. These requests will be logged in the staff action logs. schema: type: boolean - name: stats in: query description: Include user stats information schema: type: boolean - name: email in: query description: Filter to the user with this email address schema: type: string - name: ip in: query description: Filter to users with this IP address schema: type: string responses: '200': description: response content: application/json: schema: type: array minItems: 1 uniqueItems: true items: type: object properties: id: type: integer username: type: string name: type: - string - 'null' avatar_template: type: string email: type: string secondary_emails: type: array items: {} active: type: boolean admin: type: boolean moderator: type: boolean last_seen_at: type: - string - 'null' last_emailed_at: type: - string - 'null' created_at: type: string last_seen_age: type: - number - 'null' last_emailed_age: type: - number - 'null' created_at_age: type: - number - 'null' trust_level: type: integer manual_locked_trust_level: type: - string - 'null' title: type: - string - 'null' time_read: type: integer staged: type: boolean days_visited: type: integer posts_read_count: type: integer topics_entered: type: integer post_count: type: integer required: - id - username - name - avatar_template - active - admin - moderator - last_seen_at - last_emailed_at - created_at - last_seen_age - last_emailed_age - created_at_age - trust_level - manual_locked_trust_level - title - time_read - staged - days_visited - posts_read_count - topics_entered - post_count "/user_actions.json": get: summary: Get a list of user actions tags: - Users operationId: listUserActions parameters: - name: offset in: query required: true schema: type: integer - name: username in: query required: true schema: type: string - name: filter in: query required: true schema: type: string responses: '200': description: response content: application/json: schema: additionalProperties: false properties: user_actions: type: array items: type: object additionalProperties: false properties: excerpt: type: string action_type: type: integer created_at: type: string avatar_template: type: string acting_avatar_template: type: string slug: type: string topic_id: type: integer target_user_id: type: integer target_name: type: - string - 'null' target_username: type: string post_number: type: integer post_id: type: - string - 'null' username: type: string name: type: - string - 'null' user_id: type: integer acting_username: type: string acting_name: type: - string - 'null' acting_user_id: type: integer title: type: string deleted: type: boolean hidden: type: - string - 'null' post_type: type: - string - 'null' action_code: type: - string - 'null' category_id: type: integer closed: type: boolean archived: type: boolean required: - excerpt - action_type - created_at - avatar_template - acting_avatar_template - slug - topic_id - target_user_id - target_name - target_username - post_number - post_id - username - name - user_id - acting_username - acting_name - acting_user_id - title - deleted - hidden - post_type - action_code - category_id - closed - archived required: - user_actions "/session/forgot_password.json": post: summary: Send password reset email tags: - Users operationId: sendPasswordResetEmail parameters: [] responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: success: type: string user_found: type: boolean required: - success - user_found requestBody: content: application/json: schema: additionalProperties: false properties: login: type: string required: - login "/users/password-reset/{token}.json": put: summary: Change password tags: - Users operationId: changePassword parameters: - name: token in: path required: true schema: type: string responses: '200': description: success response requestBody: content: application/json: schema: additionalProperties: false properties: username: type: string password: type: string required: - username - password "/u/{username}/emails.json": get: summary: Get email addresses belonging to a user tags: - Users operationId: getUserEmails parameters: - name: username in: path required: true schema: type: string responses: '200': description: success response content: application/json: schema: additionalProperties: false properties: email: type: string secondary_emails: type: array items: {} unconfirmed_emails: type: array items: {} associated_accounts: type: array items: {} required: - email - secondary_emails - unconfirmed_emails - associated_accounts servers: - url: https://{defaultHost} variables: defaultHost: default: discourse.example.com components: schemas: {}