From e89b82735dd94efc2d4dbc890cff1c4b4234824b Mon Sep 17 00:00:00 2001 From: Luke Hagar Date: Wed, 10 Jan 2024 09:37:35 -0600 Subject: [PATCH] Create discourse-api-spec.yaml --- discourse-api-spec.yaml | 11642 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 11642 insertions(+) create mode 100644 discourse-api-spec.yaml diff --git a/discourse-api-spec.yaml b/discourse-api-spec.yaml new file mode 100644 index 0000000..a9e83c5 --- /dev/null +++ b/discourse-api-spec.yaml @@ -0,0 +1,11642 @@ +--- +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 +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: '' + 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: '' + 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: {}