@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Discourse API Documentation
@base https://discourse.example.com
@version latest
@auth ApiKey token in query
@endpoints 93
@hint download_for_search
@toc discourse-post-event(2), admin(20), categories.json(2), categories(1), c(2), groups(6), groups.json(1), invites.json(1), invites(1), notifications.json(1), notifications(1), posts.json(2), posts(5), post_actions.json(1), topics(2), search.json(1), site.json(1), site(1), tag_groups.json(2), tag_groups(2), tags.json(1), tag(1), t(12), latest.json(1), top.json(1), uploads.json(1), uploads(6), user-badges(1), users.json(1), u(8), directory_items.json(1), user_avatar(1), user_actions.json(1), session(1), users(1)

@group discourse-post-event
@endpoint GET /discourse-post-event/events.json
@optional {include_details: str(true/false), category_id: int, include_subcategories: str(true/false), post_id: int, attending_user: str, before: str(date-time), after: str(date-time), order: str(asc/desc), limit: int}
@returns(200) {events: [map]}

@endpoint GET /discourse-post-event/events.ics
@optional {category_id: int, include_subcategories: str(true/false), attending_user: str, before: str(date-time), after: str(date-time), order: str(asc/desc), limit: int}
@returns(200)

@endgroup

@group admin
@endpoint GET /admin/backups.json
@returns(200)

@endpoint POST /admin/backups.json
@required {with_uploads: bool}
@returns(200) {success: str}

@endpoint PUT /admin/backups/{filename}
@required {filename: str}
@returns(200)

@endpoint GET /admin/backups/{filename}
@required {filename: str, token: str}
@returns(200)

@endpoint GET /admin/badges.json
@returns(200) {badges: [map], badge_types: [map], badge_groupings: [map], admin_badges: map{protected_system_fields: [any], triggers: map{user_change: int, none: int, post_revision: int, trust_level_change: int, post_action: int}, badge_ids: [any], badge_grouping_ids: [any], badge_type_ids: [any]}}

@endpoint POST /admin/badges.json
@required {name: str, badge_type_id: int}
@returns(200) {badge_types: [map], badge: map{id: int, name: str, description: str, grant_count: int, allow_title: bool, multiple_grant: bool, icon: str, image_url: str?, image_upload_id: int?, listable: bool, enabled: bool, badge_grouping_id: int, system: bool, long_description: str, slug: str, manually_grantable: bool, query: str?, trigger: str?, target_posts: bool, auto_revoke: bool, show_posts: bool, badge_type_id: int, show_in_post_header: bool}}

@endpoint PUT /admin/badges/{id}.json
@required {id: int, name: str, badge_type_id: int}
@returns(200) {badge_types: [map], badge: map{id: int, name: str, description: str, grant_count: int, allow_title: bool, multiple_grant: bool, icon: str, image_url: str?, image_upload_id: int?, listable: bool, enabled: bool, badge_grouping_id: int, system: bool, long_description: str, slug: str, manually_grantable: bool, query: str?, trigger: str?, target_posts: bool, auto_revoke: bool, show_posts: bool, badge_type_id: int, show_in_post_header: bool}}

@endpoint DELETE /admin/badges/{id}.json
@required {id: int}
@returns(200)

@endgroup

@group categories.json
@endpoint POST /categories.json
@required {name: str}
@optional {color: str, text_color: str, style_type: str, emoji: str, icon: str, parent_category_id: int, allow_badges: bool, slug: str, topic_featured_links_allowed: bool, permissions: map{everyone: int, staff: int}, search_priority: int, form_template_ids: [any], category_localizations: [map{id: int, locale!: str, name!: str, description: str}]}
@returns(200) {category: map{id: int, name: str, color: str, text_color: str, style_type: str, emoji: str?, icon: str?, slug: str, locale: str?, topic_count: int, post_count: int, position: int, description: str?, description_text: str?, description_excerpt: str?, topic_url: str?, read_restricted: bool, permission: int?, notification_level: int, can_edit: bool, topic_template: str?, topic_title_placeholder: str?, form_template_ids: [any], has_children: bool?, subcategory_count: int?, sort_order: str?, sort_ascending: str?, show_subcategory_list: bool, num_featured_topics: int, default_view: str?, subcategory_list_style: str, default_top_period: str, default_list_filter: str, minimum_required_tags: int, navigate_to_first_post_after_read: bool, custom_fields: map, allowed_tags: [any], allowed_tag_groups: [any], allow_global_tags: bool, required_tag_groups: [map], category_setting: map{auto_bump_cooldown_days: int, num_auto_bump_daily: int?, require_reply_approval: bool?, require_topic_approval: bool?}, category_localizations: [any], read_only_banner: str?, available_groups: [any], auto_close_hours: str?, auto_close_based_on_last_post: bool, allow_unlimited_owner_edits_on_first_post: bool, default_slow_mode_seconds: str?, group_permissions: [map], email_in: str?, email_in_allow_strangers: bool, mailinglist_mirror: bool, all_topics_wiki: bool, can_delete: bool, allow_badges: bool, topic_featured_link_allowed: bool, search_priority: int, uploaded_logo: str?, uploaded_logo_dark: str?, uploaded_background: str?, uploaded_background_dark: str?, category_types: map}}

@endpoint GET /categories.json
@optional {include_subcategories: bool}
@returns(200) {category_list: map{can_create_category: bool, can_create_topic: bool, categories: [map]}}

@endgroup

@group categories
@endpoint PUT /categories/{id}.json
@required {id: int, name: str}
@optional {color: str, text_color: str, style_type: str, emoji: str, icon: str, parent_category_id: int, allow_badges: bool, slug: str, topic_featured_links_allowed: bool, permissions: map{everyone: int, staff: int}, search_priority: int, form_template_ids: [any], category_localizations: [map{id: int, locale!: str, name!: str, description: str}]}
@returns(200) {success: str, category: map{id: int, name: str, color: str, text_color: str, style_type: str, emoji: str?, icon: str?, slug: str, locale: str?, topic_count: int, post_count: int, position: int, description: str?, description_text: str?, description_excerpt: str?, topic_url: str?, read_restricted: bool, permission: int?, notification_level: int, can_edit: bool, topic_template: str?, topic_title_placeholder: str?, form_template_ids: [any], has_children: bool?, subcategory_count: int?, sort_order: str?, sort_ascending: str?, show_subcategory_list: bool, num_featured_topics: int, default_view: str?, subcategory_list_style: str, default_top_period: str, default_list_filter: str, minimum_required_tags: int, navigate_to_first_post_after_read: bool, custom_fields: map, allowed_tags: [any], allowed_tag_groups: [any], allow_global_tags: bool, required_tag_groups: [map], category_setting: map{auto_bump_cooldown_days: int, num_auto_bump_daily: int?, require_reply_approval: bool?, require_topic_approval: bool?}, category_localizations: [any], read_only_banner: str?, available_groups: [any], auto_close_hours: str?, auto_close_based_on_last_post: bool, allow_unlimited_owner_edits_on_first_post: bool, default_slow_mode_seconds: str?, group_permissions: [map], email_in: str?, email_in_allow_strangers: bool, mailinglist_mirror: bool, all_topics_wiki: bool, can_delete: bool, allow_badges: bool, topic_featured_link_allowed: bool, search_priority: int, uploaded_logo: str?, uploaded_logo_dark: str?, uploaded_background: str?, uploaded_background_dark: str?, category_types: map}}

@endgroup

@group c
@endpoint GET /c/{slug}/{id}.json
@required {slug: str, id: int}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, per_page: int, top_tags: [map], topics: [map]}}

@endpoint GET /c/{id}/show.json
@required {id: int}
@returns(200) {category: map{id: int, name: str, color: str, text_color: str, style_type: str, emoji: str?, icon: str?, slug: str, locale: str?, topic_count: int, post_count: int, position: int, description: str?, description_text: str?, description_excerpt: str?, topic_url: str?, read_restricted: bool, permission: int?, notification_level: int, can_edit: bool, topic_template: str?, topic_title_placeholder: str?, form_template_ids: [any], has_children: bool?, subcategory_count: int?, sort_order: str?, sort_ascending: str?, show_subcategory_list: bool, num_featured_topics: int, default_view: str?, subcategory_list_style: str, default_top_period: str, default_list_filter: str, minimum_required_tags: int, navigate_to_first_post_after_read: bool, custom_fields: map, allowed_tags: [any], allowed_tag_groups: [any], allow_global_tags: bool, required_tag_groups: [map], category_setting: map{auto_bump_cooldown_days: int, num_auto_bump_daily: int?, require_reply_approval: bool?, require_topic_approval: bool?}, category_localizations: [any], read_only_banner: str?, available_groups: [any], auto_close_hours: str?, auto_close_based_on_last_post: bool, allow_unlimited_owner_edits_on_first_post: bool, default_slow_mode_seconds: str?, group_permissions: [map], email_in: str?, email_in_allow_strangers: bool, mailinglist_mirror: bool, all_topics_wiki: bool, can_delete: bool, allow_badges: bool, topic_featured_link_allowed: bool, search_priority: int, uploaded_logo: str?, uploaded_logo_dark: str?, uploaded_background: str?, uploaded_background_dark: str?, category_types: map}}

@endgroup

@group admin
@endpoint POST /admin/groups.json
@required {group: map{name!: str, full_name: str, bio_raw: str, usernames: str, owner_usernames: str, automatic_membership_email_domains: str, visibility_level: int, primary_group: bool, flair_icon: str, flair_upload_id: int, flair_bg_color: str, public_admission: bool, public_exit: bool, default_notification_level: int, muted_category_ids: [int], regular_category_ids: [int], watching_category_ids: [int], tracking_category_ids: [int], watching_first_post_category_ids: [int]}}
@returns(200) {basic_group: map{id: int, automatic: bool, name: str, user_count: int, mentionable_level: int, messageable_level: int, visibility_level: int, primary_group: bool, title: str?, grant_trust_level: str?, incoming_email: str?, has_messages: bool, flair_url: str?, flair_bg_color: str?, flair_color: str?, bio_raw: str?, bio_cooked: str?, bio_excerpt: str?, public_admission: bool, public_exit: bool, allow_membership_requests: bool, full_name: str?, default_notification_level: int, membership_request_template: str?, members_visibility_level: int, can_see_members: bool, can_admin_group: bool, can_edit_group: bool, publish_read_state: bool}}

@endpoint DELETE /admin/groups/{id}.json
@required {id: int}
@returns(200) {success: str}

@endgroup

@group groups
@endpoint GET /groups/{name}.json
@required {name: str}
@returns(200) {group: map{id: int, automatic: bool, name: str, user_count: int, mentionable_level: int, messageable_level: int, visibility_level: int, primary_group: bool, title: str?, grant_trust_level: str?, incoming_email: str?, has_messages: bool, flair_url: str?, flair_bg_color: str?, flair_color: str?, bio_raw: str?, bio_cooked: str?, bio_excerpt: str?, public_admission: bool, public_exit: bool, allow_membership_requests: bool, full_name: str?, default_notification_level: int, membership_request_template: str?, is_group_user: bool, members_visibility_level: int, can_see_members: bool, can_admin_group: bool, can_edit_group: bool, publish_read_state: bool, is_group_owner_display: bool, mentionable: bool, messageable: bool, automatic_membership_email_domains: str?, smtp_updated_at: str?, smtp_updated_by: map?, smtp_enabled: bool, smtp_server: str?, smtp_port: str?, smtp_ssl_mode: int?, email_username: str?, email_from_alias: str?, email_password: str?, message_count: int, allow_unknown_sender_topic_replies: bool, associated_group_ids: [any], watching_category_ids: [any], tracking_category_ids: [any], watching_first_post_category_ids: [any], regular_category_ids: [any], muted_category_ids: [any], watching_tags: [any], watching_first_post_tags: [any], tracking_tags: [any], regular_tags: [any], muted_tags: [any]}, extras: map{visible_group_names: [any]}}

@endpoint PUT /groups/{id}.json
@required {id: int, group: map{name!: str, full_name: str, bio_raw: str, usernames: str, owner_usernames: str, automatic_membership_email_domains: str, visibility_level: int, primary_group: bool, flair_icon: str, flair_upload_id: int, flair_bg_color: str, public_admission: bool, public_exit: bool, default_notification_level: int, muted_category_ids: [int], regular_category_ids: [int], watching_category_ids: [int], tracking_category_ids: [int], watching_first_post_category_ids: [int]}}
@returns(200) {success: str}

@endpoint GET /groups/by-id/{id}.json
@required {id: str}
@returns(200) {group: map{id: int, automatic: bool, name: str, user_count: int, mentionable_level: int, messageable_level: int, visibility_level: int, primary_group: bool, title: str?, grant_trust_level: str?, incoming_email: str?, has_messages: bool, flair_url: str?, flair_bg_color: str?, flair_color: str?, bio_raw: str?, bio_cooked: str?, bio_excerpt: str?, public_admission: bool, public_exit: bool, allow_membership_requests: bool, full_name: str?, default_notification_level: int, membership_request_template: str?, is_group_user: bool, members_visibility_level: int, can_see_members: bool, can_admin_group: bool, can_edit_group: bool, publish_read_state: bool, is_group_owner_display: bool, mentionable: bool, messageable: bool, automatic_membership_email_domains: str?, smtp_updated_at: str?, smtp_updated_by: map?, smtp_enabled: bool, smtp_server: str?, smtp_port: str?, smtp_ssl_mode: int?, email_username: str?, email_from_alias: str?, email_password: str?, message_count: int, allow_unknown_sender_topic_replies: bool, associated_group_ids: [any], watching_category_ids: [any], tracking_category_ids: [any], watching_first_post_category_ids: [any], regular_category_ids: [any], muted_category_ids: [any], watching_tags: [any], watching_first_post_tags: [any], tracking_tags: [any], regular_tags: [any], muted_tags: [any]}, extras: map{visible_group_names: [any]}}

@endpoint GET /groups/{name}/members.json
@required {name: str}
@returns(200) {members: [map], owners: [map], meta: map{total: int, limit: int, offset: int}}

@endpoint PUT /groups/{id}/members.json
@required {id: int}
@optional {usernames: str}
@returns(200) {success: str, usernames: [any], emails: [any]}

@endpoint DELETE /groups/{id}/members.json
@required {id: int}
@optional {usernames: str}
@returns(200) {success: str, usernames: [any], skipped_usernames: [any]}

@endgroup

@group groups.json
@endpoint GET /groups.json
@returns(200) {groups: [map], extras: map{type_filters: [any]}, total_rows_groups: int, load_more_groups: str}

@endgroup

@group invites.json
@endpoint POST /invites.json
@required {Api-Key: str, Api-Username: str}
@optional {email: str, skip_email: bool=false, custom_message: str, max_redemptions_allowed: int=1, topic_id: int, group_ids: str, group_names: str, expires_at: str}
@returns(200) {id: int, invite_key: str, link: str, description: str?, email: str, domain: str?, emailed: bool, can_delete_invite: bool, custom_message: str?, created_at: str, updated_at: str, expires_at: str, expired: bool, topics: [map], groups: [map]}

@endgroup

@group invites
@endpoint POST /invites/create-multiple.json
@required {Api-Key: str, Api-Username: str}
@optional {email: str, skip_email: bool=false, custom_message: str, max_redemptions_allowed: int=1, topic_id: int, group_ids: str, group_names: str, expires_at: str}
@returns(200) {num_successfully_created_invitations: int, num_failed_invitations: int, failed_invitations: [any], successful_invitations: [any]}

@endgroup

@group notifications.json
@endpoint GET /notifications.json
@returns(200) {notifications: [map], total_rows_notifications: int, seen_notification_id: int, load_more_notifications: str}

@endgroup

@group notifications
@endpoint PUT /notifications/mark-read.json
@optional {id: int}
@returns(200) {success: str}

@endgroup

@group posts.json
@endpoint GET /posts.json
@optional {before: int}
@returns(200) {latest_posts: [map]}

@endpoint POST /posts.json
@required {raw: str}
@optional {title: str, topic_id: int, category: int, target_recipients: str, target_usernames: str, archetype: str, created_at: str, reply_to_post_number: int, embed_url: str, external_id: str, auto_track: bool}
@returns(200) {id: int, name: str?, username: str, avatar_template: str, created_at: str, raw: str, cooked: str, post_number: int, post_type: int, posts_count: int, updated_at: str, reply_count: int, reply_to_post_number: str?, quote_count: int, incoming_link_count: int, reads: int, readers_count: int, score: num, yours: bool, topic_id: int, topic_slug: str, display_username: str?, primary_group_name: str?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, flair_group_id: int?, badges_granted: [any], version: int, can_edit: bool, can_delete: bool, can_recover: bool, can_see_hidden_post: bool, can_wiki: bool, user_title: str?, bookmarked: bool, actions_summary: [map], moderator: bool, admin: bool, staff: bool, user_id: int, draft_sequence: int, hidden: bool, trust_level: int, deleted_at: str?, user_deleted: bool, edit_reason: str?, can_view_edit_history: bool, wiki: bool, reviewable_id: int?, reviewable_score_count: int, reviewable_score_pending_count: int, post_url: str, post_localizations: [any], mentioned_users: [any]}

@endgroup

@group posts
@endpoint GET /posts/{id}.json
@required {id: str}
@returns(200) {id: int, username: str, avatar_template: str, created_at: str, cooked: str, post_number: int, post_type: int, posts_count: int, updated_at: str, reply_count: int, reply_to_post_number: str?, quote_count: int, incoming_link_count: int, reads: int, readers_count: int, score: num, yours: bool, topic_id: int, topic_slug: str, primary_group_name: str?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, flair_group_id: int?, version: int, can_edit: bool, can_delete: bool, can_recover: bool, can_see_hidden_post: bool, can_wiki: bool, user_title: str?, bookmarked: bool, raw: str, actions_summary: [map], moderator: bool, admin: bool, staff: bool, user_id: int, hidden: bool, trust_level: int, deleted_at: str?, user_deleted: bool, edit_reason: str?, can_view_edit_history: bool, wiki: bool, reviewable_id: int?, reviewable_score_count: int, reviewable_score_pending_count: int, post_url: str, mentioned_users: [any], name: str?, display_username: str?}

@endpoint PUT /posts/{id}.json
@required {id: str}
@optional {post: map{raw!: str, edit_reason: str}, bypass_bump: bool}
@returns(200) {post: map{id: int, username: str, avatar_template: str, created_at: str, cooked: str, post_number: int, post_type: int, posts_count: int, updated_at: str, reply_count: int, reply_to_post_number: str?, quote_count: int, incoming_link_count: int, reads: int, readers_count: int, score: num, yours: bool, topic_id: int, topic_slug: str, primary_group_name: str?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, flair_group_id: int?, badges_granted: [any], version: int, can_edit: bool, can_delete: bool, can_recover: bool, can_see_hidden_post: bool, can_wiki: bool, user_title: str?, bookmarked: bool, raw: str, actions_summary: [map], moderator: bool, admin: bool, staff: bool, user_id: int, draft_sequence: int, hidden: bool, trust_level: int, deleted_at: str?, user_deleted: bool, edit_reason: str?, can_view_edit_history: bool, wiki: bool, reviewable_id: int?, reviewable_score_count: int, reviewable_score_pending_count: int, post_url: str, post_localizations: [any], mentioned_users: [any], name: str?, display_username: str?}}

@endpoint DELETE /posts/{id}.json
@required {id: int}
@optional {force_destroy: bool}
@returns(200)

@endpoint GET /posts/{id}/replies.json
@required {id: str}
@returns(200)

@endpoint PUT /posts/{id}/locked.json
@required {Api-Key: str, Api-Username: str, id: str, locked: str}
@returns(200) {locked: bool}

@endgroup

@group post_actions.json
@endpoint POST /post_actions.json
@required {Api-Key: str, Api-Username: str, id: int, post_action_type_id: int}
@optional {flag_topic: bool}
@returns(200) {id: int, name: str, username: str, avatar_template: str, created_at: str, cooked: str, post_number: int, post_type: int, posts_count: int, updated_at: str, reply_count: int, reply_to_post_number: str?, quote_count: int, incoming_link_count: int, reads: int, readers_count: int, score: num, yours: bool, topic_id: int, topic_slug: str, display_username: str, primary_group_name: str?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, flair_group_id: int?, badges_granted: [any], version: int, can_edit: bool, can_delete: bool, can_recover: bool, can_see_hidden_post: bool, can_wiki: bool, user_title: str?, bookmarked: bool, actions_summary: [map], moderator: bool, admin: bool, staff: bool, user_id: int, hidden: bool, trust_level: int, deleted_at: str?, user_deleted: bool, edit_reason: str?, can_view_edit_history: bool, wiki: bool, reviewable_id: int?, reviewable_score_count: int, reviewable_score_pending_count: int, post_url: str}

@endgroup

@group topics
@endpoint GET /topics/private-messages/{username}.json
@required {username: str}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, draft: str?, draft_key: str, draft_sequence: int, per_page: int, topics: [map]}}

@endpoint GET /topics/private-messages-sent/{username}.json
@required {username: str}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, draft: str?, draft_key: str, draft_sequence: int, per_page: int, topics: [map]}}

@endgroup

@group search.json
@endpoint GET /search.json
@optional {q: str, page: int}
@returns(200) {posts: [any], users: [any], categories: [any], tags: [map], groups: [any], grouped_search_result: map{more_posts: str?, more_users: str?, more_categories: str?, term: str, search_log_id: int, more_full_page_results: str?, can_create_topic: bool, error: str?, extra: map{categories: [any]?}, post_ids: [any], user_ids: [any], category_ids: [any], tag_ids: [any], group_ids: [any]}}

@endgroup

@group site.json
@endpoint GET /site.json
@returns(200) {default_archetype: str, notification_types: map{mentioned: int, replied: int, quoted: int, edited: int, liked: int, private_message: int, invited_to_private_message: int, invitee_accepted: int, posted: int, watching_category_or_tag: int, new_features: int, admin_problems: int, moved_post: int, linked: int, granted_badge: int, invited_to_topic: int, custom: int, group_mentioned: int, group_message_summary: int, watching_first_post: int, topic_reminder: int, liked_consolidated: int, linked_consolidated: int, post_approved: int, code_review_commit_approved: int, membership_request_accepted: int, membership_request_consolidated: int, bookmark_reminder: int, reaction: int, votes_released: int, event_reminder: int, event_invitation: int, chat_mention: int, chat_message: int, chat_invitation: int, chat_group_mention: int, chat_quoted: int, chat_watched_thread: int, upcoming_change_available: int, upcoming_change_automatically_promoted: int, assigned: int, question_answer_user_commented: int, following: int, following_created_topic: int, following_replied: int, circles_activity: int, boost: int}, post_types: map{regular: int, moderator_action: int, small_action: int, whisper: int}, trust_levels: map{newuser: int, basic: int, member: int, regular: int, leader: int}, user_tips: map{first_notification: int, topic_timeline: int, post_menu: int, topic_notification_levels: int, suggested_topics: int}, groups: [map], filters: [any], periods: [any], top_menu_items: [any], anonymous_top_menu_items: [any], uncategorized_category_id: int, user_field_max_length: int, post_action_types: [map], topic_flag_types: [map], can_create_tag: bool, can_tag_topics: bool, can_tag_pms: bool, tags_filter_regexp: str, top_tags: [map], wizard_required: bool, can_associate_groups: bool, email_configured: bool, topic_featured_link_allowed_category_ids: [any], user_themes: [map], user_color_schemes: [map], default_light_color_scheme: map?, default_dark_color_scheme: map?, censored_regexp: [map], custom_emoji_translation: map, watched_words_replace: str?, watched_words_link: str?, markdown_additional_options: map, hashtag_configurations: map, hashtag_icons: map, displayed_about_plugin_stat_groups: [any], categories: [map], archetypes: [map], user_fields: [any], auth_providers: [any], whispers_allowed_groups_names: [any], denied_emojis: [any], valid_flag_applies_to_types: [any], navigation_menu_site_top_tags: [any], full_name_required_for_signup: bool, full_name_visible_in_signup: bool, admin_config_login_routes: [any]}

@endgroup

@group site
@endpoint GET /site/basic-info.json
@returns(200) {logo_url: str, logo_small_url: str, apple_touch_icon_url: str, favicon_url: str, title: str, description: str, header_primary_color: str, header_background_color: str, login_required: bool, locale: str, include_in_discourse_discover: bool, mobile_logo_url: str}

@endgroup

@group tag_groups.json
@endpoint GET /tag_groups.json
@returns(200) {tag_groups: [map]}

@endpoint POST /tag_groups.json
@required {name: str}
@returns(200) {tag_group: map{id: int, name: str, tags: [map], parent_tag: [map], one_per_topic: bool, permissions: map}}

@endgroup

@group tag_groups
@endpoint GET /tag_groups/{id}.json
@required {id: str}
@returns(200) {tag_group: map{id: int, name: str, tag_names: [any], parent_tag_name: [any], one_per_topic: bool, permissions: map{everyone: int}}}

@endpoint PUT /tag_groups/{id}.json
@required {id: str}
@optional {name: str}
@returns(200) {success: str, tag_group: map{id: int, name: str, tag_names: [any], parent_tag_name: [any], one_per_topic: bool, permissions: map{everyone: int}}}

@endgroup

@group tags.json
@endpoint GET /tags.json
@returns(200) {tags: [map], extras: map{categories: [any]}}

@endgroup

@group tag
@endpoint GET /tag/{name}.json
@required {name: str}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, draft: str?, draft_key: str, draft_sequence: int, per_page: int, tags: [map], topics: [map]}}

@endgroup

@group t
@endpoint GET /t/{id}/posts.json
@required {Api-Key: str, Api-Username: str, id: str, post_ids[]: int}
@returns(200) {post_stream: map{posts: [map]}, id: int}

@endpoint GET /t/{id}.json
@required {Api-Key: str, Api-Username: str, id: str}
@returns(200) {post_stream: map{posts: [map], stream: [any]}, timeline_lookup: [any], suggested_topics: [map], tags: [map], tags_descriptions: map, id: int, title: str, fancy_title: str, posts_count: int, created_at: str, views: int, reply_count: int, like_count: int, last_posted_at: str?, visible: bool, closed: bool, archived: bool, has_summary: bool, archetype: str, slug: str, category_id: int, word_count: int?, deleted_at: str?, user_id: int, featured_link: str?, pinned_globally: bool, pinned_at: str?, pinned_until: str?, image_url: str?, slow_mode_seconds: int, draft: str?, draft_key: str, draft_sequence: int, unpinned: str?, pinned: bool, current_post_number: int, highest_post_number: int?, deleted_by: str?, has_deleted: bool, actions_summary: [map], chunk_size: int, bookmarked: bool, bookmarks: [any], topic_timer: str?, message_bus_last_id: int, participant_count: int, show_read_indicator: bool, thumbnails: str?, slow_mode_enabled_until: str?, details: map{can_edit: bool, notification_level: int, can_move_posts: bool, can_delete: bool, can_remove_allowed_users: bool, can_create_post: bool, can_reply_as_new_topic: bool, can_invite_to: bool, can_invite_via_email: bool, can_flag_topic: bool, can_convert_topic: bool, can_review_topic: bool, can_close_topic: bool, can_archive_topic: bool, can_split_merge_topic: bool, can_edit_staff_notes: bool, can_toggle_topic_visibility: bool, can_pin_unpin_topic: bool, can_banner_topic: bool, can_moderate_category: bool, can_remove_self_id: int, participants: [map], created_by: map{id: int, username: str, name: str, avatar_template: str}, last_poster: map{id: int, username: str, name: str, avatar_template: str}}}

@endpoint DELETE /t/{id}.json
@required {Api-Key: str, Api-Username: str, id: str}
@returns(200)

@endpoint PUT /t/-/{id}.json
@required {Api-Key: str, Api-Username: str, id: str}
@optional {topic: map{title: str, category_id: int}}
@returns(200) {basic_topic: map{id: int, title: str, fancy_title: str, slug: str, posts_count: int}}

@endpoint POST /t/{id}/invite.json
@required {Api-Key: str, Api-Username: str, id: str}
@optional {user: str, email: str}
@returns(200) {user: map{id: int, username: str, name: str, avatar_template: str}}

@endpoint POST /t/{id}/invite-group.json
@required {Api-Key: str, Api-Username: str, id: str}
@optional {group: str, should_notify: bool}
@returns(200) {group: map{id: int, name: str}}

@endpoint PUT /t/{id}/bookmark.json
@required {Api-Key: str, Api-Username: str, id: str}
@returns(200)

@endpoint PUT /t/{id}/status.json
@required {Api-Key: str, Api-Username: str, id: str, status: str(closed/pinned/pinned_globally/archived/visible), enabled: str(true/false)}
@optional {until: str}
@returns(200) {success: str, topic_status_update: str?}

@endgroup

@group latest.json
@endpoint GET /latest.json
@required {Api-Key: str, Api-Username: str}
@optional {order: str, ascending: str, per_page: int}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, draft: str?, draft_key: str, draft_sequence: int, per_page: int, topics: [map]}}

@endgroup

@group top.json
@endpoint GET /top.json
@required {Api-Key: str, Api-Username: str}
@optional {period: str, per_page: int}
@returns(200) {users: [map], primary_groups: [any], topic_list: map{can_create_topic: bool, draft: str?, draft_key: str, draft_sequence: int, for_period: str, per_page: int, topics: [map]}}

@endgroup

@group t
@endpoint POST /t/{id}/notifications.json
@required {Api-Key: str, Api-Username: str, id: str, notification_level: str(0/1/2/3)}
@returns(200) {success: str}

@endpoint PUT /t/{id}/change-timestamp.json
@required {Api-Key: str, Api-Username: str, id: str, timestamp: str}
@returns(200) {success: str}

@endpoint POST /t/{id}/timer.json
@required {Api-Key: str, Api-Username: str, id: str}
@optional {time: str, status_type: str, based_on_last_post: bool, category_id: int}
@returns(200) {success: str, execute_at: str, duration: str?, based_on_last_post: bool, closed: bool, category_id: int?}

@endpoint GET /t/external_id/{external_id}.json
@required {external_id: str}
@errors {301}

@endgroup

@group uploads.json
@endpoint POST /uploads.json
@returns(200) {id: int, url: str, original_filename: str, filesize: int, width: int, height: int, thumbnail_width: int, thumbnail_height: int, extension: str, short_url: str, short_path: str, retain_hours: str?, human_filesize: str, dominant_color: str?, thumbnail: map?, optimized_video: map?}

@endgroup

@group uploads
@endpoint POST /uploads/generate-presigned-put.json
@required {type: str(avatar/profile_background/card_background/custom_emoji/composer), file_name: str, file_size: int}
@optional {metadata: map{sha1-checksum: str}}
@returns(200) {key: str, url: str, signed_headers: map, unique_identifier: str}

@endpoint POST /uploads/complete-external-upload.json
@required {unique_identifier: str}
@optional {for_private_message: str, for_site_setting: str, pasted: str}
@returns(200) {id: int, url: str, original_filename: str, filesize: int, width: int, height: int, thumbnail_width: int, thumbnail_height: int, extension: str, short_url: str, short_path: str, retain_hours: str?, human_filesize: str, dominant_color: str?, thumbnail: map?, optimized_video: map?}

@endpoint POST /uploads/create-multipart.json
@required {upload_type: str(avatar/profile_background/card_background/custom_emoji/composer), file_name: str, file_size: int}
@optional {metadata: map{sha1-checksum: str}}
@returns(200) {key: str, external_upload_identifier: str, unique_identifier: str}

@endpoint POST /uploads/batch-presign-multipart-parts.json
@required {part_numbers: [any], unique_identifier: str}
@returns(200) {presigned_urls: map}

@endpoint POST /uploads/abort-multipart.json
@required {external_upload_identifier: str}
@returns(200) {success: str}

@endpoint POST /uploads/complete-multipart.json
@required {unique_identifier: str, parts: [any]}
@returns(200) {id: int, url: str, original_filename: str, filesize: int, width: int, height: int, thumbnail_width: int, thumbnail_height: int, extension: str, short_url: str, short_path: str, retain_hours: str?, human_filesize: str, dominant_color: str?, thumbnail: map?, optimized_video: map?}

@endgroup

@group user-badges
@endpoint GET /user-badges/{username}.json
@required {username: str}
@returns(200) {badges: [map], badge_types: [map], granted_bies: [map], user_badges: [map]}

@endgroup

@group users.json
@endpoint POST /users.json
@required {Api-Key: str, Api-Username: str, name: str, email: str, password: str, username: str}
@optional {active: bool, approved: bool, user_fields: map{1: bool}, external_ids: map}
@returns(200) {success: bool, active: bool, message: str, user_id: int}

@endgroup

@group u
@endpoint GET /u/{username}.json
@required {Api-Key: str, Api-Username: str, username: str}
@returns(200) {user_badges: [any], user: map{id: int, username: str, name: str, avatar_template: str, last_posted_at: str?, last_seen_at: str?, created_at: str, ignored: bool, muted: bool, can_ignore_user: bool, can_ignore_users: bool, can_mute_user: bool, can_mute_users: bool, can_send_private_messages: bool, can_send_private_message_to_user: bool, trust_level: int, moderator: bool, admin: bool, title: str?, badge_count: int, second_factor_backup_enabled: bool, user_fields: map{1: str?, 2: str?}, custom_fields: map{first_name: str?}, time_read: int, recent_time_read: int, primary_group_id: int?, primary_group_name: str?, flair_group_id: int?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, featured_topic: str?, staged: bool, can_edit: bool, can_edit_username: bool, can_edit_email: bool, can_edit_name: bool, uploaded_avatar_id: int?, has_title_badges: bool, pending_count: int, pending_posts_count: int, profile_view_count: int, second_factor_enabled: bool, can_upload_profile_header: bool, can_upload_user_card_background: bool, post_count: int, topic_count: int, can_be_deleted: bool, can_delete_all_posts: bool, locale: str?, muted_category_ids: [any], regular_category_ids: [any], watched_tags: [any], watching_first_post_tags: [any], tracked_tags: [any], muted_tags: [any], tracked_category_ids: [any], watched_category_ids: [any], watched_first_post_category_ids: [any], system_avatar_upload_id: str?, system_avatar_template: str, muted_usernames: [any], ignored_usernames: [any], allowed_pm_usernames: [any], mailing_list_posts_per_day: int, can_change_bio: bool, can_change_location: bool, can_change_website: bool, can_change_tracking_preferences: bool, user_api_keys: str?, user_passkeys: [any], sidebar_tags: [any], sidebar_category_ids: [any], display_sidebar_tags: bool, can_pick_theme_with_custom_homepage: bool, user_auth_tokens: [map], user_notification_schedule: map{enabled: bool, day_0_start_time: int, day_0_end_time: int, day_1_start_time: int, day_1_end_time: int, day_2_start_time: int, day_2_end_time: int, day_3_start_time: int, day_3_end_time: int, day_4_start_time: int, day_4_end_time: int, day_5_start_time: int, day_5_end_time: int, day_6_start_time: int, day_6_end_time: int}, use_logo_small_as_avatar: bool, featured_user_badge_ids: [any], invited_by: str?, groups: [map], group_users: [map], user_option: map{user_id: int, mailing_list_mode: bool, mailing_list_mode_frequency: int, email_digests: bool, email_level: int, email_messages_level: int, external_links_in_new_tab: bool, bookmark_auto_delete_preference: int, color_scheme_id: str?, dark_scheme_id: str?, dynamic_favicon: bool, enable_quoting: bool, enable_smart_lists: bool, enable_markdown_monospace_font: bool, enable_defer: bool, digest_after_minutes: int, automatically_unpin_topics: bool, auto_track_topics_after_msecs: int, notification_level_when_replying: int, new_topic_duration_minutes: int, email_previous_replies: int, email_in_reply_to: bool, like_notification_frequency: int, notify_on_linked_posts: bool, include_tl0_in_digests: bool, theme_ids: [any], theme_key_seq: int, allow_private_messages: bool, enable_allowed_pm_users: bool, homepage_id: str?, hide_profile_and_presence: bool, hide_profile: bool, hide_presence: bool, text_size: str, text_size_seq: int, title_count_mode: str, timezone: str?, skip_new_user_tips: bool, default_calendar: str, oldest_search_log_date: str?, sidebar_link_to_filtered_list: bool, sidebar_show_count_of_new_items: bool, watched_precedence_over_muted: bool, seen_popups: [any]?, topics_unread_when_closed: bool, composition_mode: int, interface_color_mode: int}}}

@endpoint PUT /u/{username}.json
@required {Api-Key: str, Api-Username: str, username: str}
@optional {name: str, external_ids: map}
@returns(200) {success: str, user: map}

@endpoint GET /u/by-external/{external_id}.json
@required {Api-Key: str, Api-Username: str, external_id: str}
@returns(200) {user_badges: [any], user: map{id: int, username: str, name: str, avatar_template: str, last_posted_at: str?, last_seen_at: str?, created_at: str, ignored: bool, muted: bool, can_ignore_user: bool, can_ignore_users: bool, can_mute_user: bool, can_mute_users: bool, can_send_private_messages: bool, can_send_private_message_to_user: bool, trust_level: int, moderator: bool, admin: bool, title: str?, badge_count: int, second_factor_backup_enabled: bool, user_fields: map{1: str?, 2: str?}, custom_fields: map{first_name: str?}, time_read: int, recent_time_read: int, primary_group_id: int?, primary_group_name: str?, flair_group_id: int?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, featured_topic: str?, staged: bool, can_edit: bool, can_edit_username: bool, can_edit_email: bool, can_edit_name: bool, uploaded_avatar_id: int?, has_title_badges: bool, pending_count: int, pending_posts_count: int, profile_view_count: int, second_factor_enabled: bool, can_upload_profile_header: bool, can_upload_user_card_background: bool, post_count: int, topic_count: int, can_be_deleted: bool, can_delete_all_posts: bool, locale: str?, muted_category_ids: [any], regular_category_ids: [any], watched_tags: [any], watching_first_post_tags: [any], tracked_tags: [any], muted_tags: [any], tracked_category_ids: [any], watched_category_ids: [any], watched_first_post_category_ids: [any], system_avatar_upload_id: str?, system_avatar_template: str, muted_usernames: [any], ignored_usernames: [any], allowed_pm_usernames: [any], mailing_list_posts_per_day: int, can_change_bio: bool, can_change_location: bool, can_change_website: bool, can_change_tracking_preferences: bool, user_api_keys: str?, user_passkeys: [any], sidebar_tags: [any], sidebar_category_ids: [any], display_sidebar_tags: bool, can_pick_theme_with_custom_homepage: bool, user_auth_tokens: [map], user_notification_schedule: map{enabled: bool, day_0_start_time: int, day_0_end_time: int, day_1_start_time: int, day_1_end_time: int, day_2_start_time: int, day_2_end_time: int, day_3_start_time: int, day_3_end_time: int, day_4_start_time: int, day_4_end_time: int, day_5_start_time: int, day_5_end_time: int, day_6_start_time: int, day_6_end_time: int}, use_logo_small_as_avatar: bool, featured_user_badge_ids: [any], invited_by: str?, groups: [map], group_users: [map], user_option: map{user_id: int, mailing_list_mode: bool, mailing_list_mode_frequency: int, email_digests: bool, email_level: int, email_messages_level: int, external_links_in_new_tab: bool, bookmark_auto_delete_preference: int, color_scheme_id: str?, dark_scheme_id: str?, dynamic_favicon: bool, enable_quoting: bool, enable_smart_lists: bool, enable_markdown_monospace_font: bool, enable_defer: bool, digest_after_minutes: int, automatically_unpin_topics: bool, auto_track_topics_after_msecs: int, notification_level_when_replying: int, new_topic_duration_minutes: int, email_previous_replies: int, email_in_reply_to: bool, like_notification_frequency: int, notify_on_linked_posts: bool, include_tl0_in_digests: bool, theme_ids: [any], theme_key_seq: int, allow_private_messages: bool, enable_allowed_pm_users: bool, homepage_id: str?, hide_profile_and_presence: bool, hide_profile: bool, hide_presence: bool, text_size: str, text_size_seq: int, title_count_mode: str, timezone: str?, skip_new_user_tips: bool, default_calendar: str, oldest_search_log_date: str?, sidebar_link_to_filtered_list: bool, sidebar_show_count_of_new_items: bool, watched_precedence_over_muted: bool, seen_popups: [any]?, topics_unread_when_closed: bool, composition_mode: int, interface_color_mode: int}}}

@endpoint GET /u/by-external/{provider}/{external_id}.json
@required {Api-Key: str, Api-Username: str, provider: str, external_id: str}
@returns(200) {user_badges: [any], user: map{id: int, username: str, name: str, avatar_template: str, last_posted_at: str?, last_seen_at: str?, created_at: str, ignored: bool, muted: bool, can_ignore_user: bool, can_ignore_users: bool, can_mute_user: bool, can_mute_users: bool, can_send_private_messages: bool, can_send_private_message_to_user: bool, trust_level: int, moderator: bool, admin: bool, title: str?, badge_count: int, second_factor_backup_enabled: bool, user_fields: map{1: str?, 2: str?}, custom_fields: map{first_name: str?}, time_read: int, recent_time_read: int, primary_group_id: int?, primary_group_name: str?, flair_group_id: int?, flair_name: str?, flair_url: str?, flair_bg_color: str?, flair_color: str?, featured_topic: str?, staged: bool, can_edit: bool, can_edit_username: bool, can_edit_email: bool, can_edit_name: bool, uploaded_avatar_id: int?, has_title_badges: bool, pending_count: int, pending_posts_count: int, profile_view_count: int, second_factor_enabled: bool, can_upload_profile_header: bool, can_upload_user_card_background: bool, post_count: int, topic_count: int, can_be_deleted: bool, can_delete_all_posts: bool, locale: str?, muted_category_ids: [any], regular_category_ids: [any], watched_tags: [any], watching_first_post_tags: [any], tracked_tags: [any], muted_tags: [any], tracked_category_ids: [any], watched_category_ids: [any], watched_first_post_category_ids: [any], system_avatar_upload_id: str?, system_avatar_template: str, muted_usernames: [any], ignored_usernames: [any], allowed_pm_usernames: [any], mailing_list_posts_per_day: int, can_change_bio: bool, can_change_location: bool, can_change_website: bool, can_change_tracking_preferences: bool, user_api_keys: str?, user_passkeys: [any], sidebar_tags: [any], sidebar_category_ids: [any], display_sidebar_tags: bool, can_pick_theme_with_custom_homepage: bool, user_auth_tokens: [map], user_notification_schedule: map{enabled: bool, day_0_start_time: int, day_0_end_time: int, day_1_start_time: int, day_1_end_time: int, day_2_start_time: int, day_2_end_time: int, day_3_start_time: int, day_3_end_time: int, day_4_start_time: int, day_4_end_time: int, day_5_start_time: int, day_5_end_time: int, day_6_start_time: int, day_6_end_time: int}, use_logo_small_as_avatar: bool, featured_user_badge_ids: [any], invited_by: str?, groups: [map], group_users: [map], user_option: map{user_id: int, mailing_list_mode: bool, mailing_list_mode_frequency: int, email_digests: bool, email_level: int, email_messages_level: int, external_links_in_new_tab: bool, bookmark_auto_delete_preference: int, color_scheme_id: str?, dark_scheme_id: str?, dynamic_favicon: bool, enable_quoting: bool, enable_smart_lists: bool, enable_markdown_monospace_font: bool, enable_defer: bool, digest_after_minutes: int, automatically_unpin_topics: bool, auto_track_topics_after_msecs: int, notification_level_when_replying: int, new_topic_duration_minutes: int, email_previous_replies: int, email_in_reply_to: bool, like_notification_frequency: int, notify_on_linked_posts: bool, include_tl0_in_digests: bool, theme_ids: [any], theme_key_seq: int, allow_private_messages: bool, enable_allowed_pm_users: bool, homepage_id: str?, hide_profile_and_presence: bool, hide_profile: bool, hide_presence: bool, text_size: str, text_size_seq: int, title_count_mode: str, timezone: str?, skip_new_user_tips: bool, default_calendar: str, oldest_search_log_date: str?, sidebar_link_to_filtered_list: bool, sidebar_show_count_of_new_items: bool, watched_precedence_over_muted: bool, seen_popups: [any]?, topics_unread_when_closed: bool, composition_mode: int, interface_color_mode: int}}}

@endpoint PUT /u/{username}/preferences/avatar/pick.json
@required {username: str, upload_id: int, type: str(uploaded/custom/gravatar/system)}
@returns(200) {success: str}

@endpoint PUT /u/{username}/preferences/email.json
@required {username: str, email: str(email)}
@returns(200)

@endpoint PUT /u/{username}/preferences/username.json
@required {username: str, new_username: str}
@returns(200)

@endgroup

@group directory_items.json
@endpoint GET /directory_items.json
@required {period: str(daily/weekly/monthly/quarterly/yearly/all), order: str(likes_received/likes_given/topic_count/post_count/topics_entered/posts_read/days_visited)}
@optional {asc: str, page: int}
@returns(200) {directory_items: [map], meta: map{last_updated_at: str?, total_rows_directory_items: int, load_more_directory_items: str}}

@endgroup

@group admin
@endpoint GET /admin/users/{id}.json
@required {id: int}
@returns(200) {id: int, username: str, name: str?, avatar_template: str, active: bool, admin: bool, moderator: bool, last_seen_at: str?, last_emailed_at: str?, created_at: str, last_seen_age: num?, last_emailed_age: num?, created_at_age: num?, trust_level: int, manual_locked_trust_level: str?, title: str?, time_read: int, staged: bool, days_visited: int, posts_read_count: int, topics_entered: int, post_count: int, associated_accounts: [any], can_send_activation_email: bool, can_activate: bool, can_deactivate: bool, can_change_trust_level: bool, ip_address: str, registration_ip_address: str?, can_grant_admin: bool, can_revoke_admin: bool, can_grant_moderation: bool, can_revoke_moderation: bool, can_impersonate: bool, like_count: int, like_given_count: int, topic_count: int, flags_given_count: int, flags_received_count: int, private_topics_count: int, can_delete_all_posts: bool, can_be_deleted: bool, can_be_anonymized: bool, can_be_merged: bool, full_suspend_reason: str?, latest_export: map?, silence_reason: str?, post_edits_count: int?, primary_group_id: int?, badge_count: int, warnings_received_count: int, bounce_score: int?, reset_bounce_score_after: str?, can_view_action_logs: bool, can_disable_second_factor: bool, can_delete_sso_record: bool, api_key_count: int, similar_users_count: int, single_sign_on_record: str?, approved_by: map?, suspended_by: str?, silenced_by: str?, penalty_counts: map{silenced: int, suspended: int}, next_penalty: str, tl3_requirements: map{time_period: int, requirements_met: bool, requirements_lost: bool, trust_level_locked: bool, on_grace_period: bool, days_visited: int, min_days_visited: int, num_topics_replied_to: int, min_topics_replied_to: int, topics_viewed: int, min_topics_viewed: int, posts_read: int, min_posts_read: int, topics_viewed_all_time: int, min_topics_viewed_all_time: int, posts_read_all_time: int, min_posts_read_all_time: int, num_flagged_posts: int, max_flagged_posts: int, num_flagged_by_users: int, max_flagged_by_users: int, num_likes_given: int, min_likes_given: int, num_likes_received: int, min_likes_received: int, num_likes_received_days: int, min_likes_received_days: int, num_likes_received_users: int, min_likes_received_users: int, penalty_counts: map{silenced: int, suspended: int, total: int}}, groups: [map], external_ids: map, include_ip: bool, upcoming_changes_stats: [map]}

@endpoint DELETE /admin/users/{id}.json
@required {id: int}
@optional {delete_posts: bool, block_email: bool, block_urls: bool, block_ip: bool}
@returns(200) {deleted: bool}

@endpoint PUT /admin/users/{id}/activate.json
@required {id: int}
@returns(200) {success: str}

@endpoint PUT /admin/users/{id}/deactivate.json
@required {id: int}
@returns(200) {success: str}

@endpoint PUT /admin/users/{id}/suspend.json
@required {id: int, suspend_until: str, reason: str}
@optional {message: str, post_action: str}
@returns(200) {suspension: map{suspend_reason: str, full_suspend_reason: str, suspended_till: str, suspended_at: str, suspended_by: map{id: int, username: str, name: str, avatar_template: str}}}

@endpoint PUT /admin/users/{id}/silence.json
@required {id: int, silenced_till: str, reason: str}
@optional {message: str, post_action: str}
@returns(200) {silence: map{silenced: bool, silence_reason: str, silenced_till: str, silenced_at: str, silenced_by: map{id: int, username: str, name: str, avatar_template: str}}}

@endpoint PUT /admin/users/{id}/anonymize.json
@required {id: int}
@returns(200) {success: str, username: str}

@endpoint POST /admin/users/{id}/log_out.json
@required {id: int}
@returns(200) {success: str}

@endgroup

@group user_avatar
@endpoint POST /user_avatar/{username}/refresh_gravatar.json
@required {username: str}
@returns(200) {gravatar_upload_id: int?, gravatar_avatar_template: str?}

@endgroup

@group admin
@endpoint GET /admin/users.json
@optional {order: str(created/last_emailed/seen/username/email/trust_level/days_visited/posts_read/topics_viewed/posts/read_time), asc: str, page: int, show_emails: bool, stats: bool, email: str, ip: str}
@returns(200)

@endpoint GET /admin/users/list/{flag}.json
@required {flag: str(active/new/staff/suspended/blocked/suspect)}
@optional {order: str(created/last_emailed/seen/username/email/trust_level/days_visited/posts_read/topics_viewed/posts/read_time), asc: str, page: int, show_emails: bool, stats: bool, email: str, ip: str}
@returns(200)

@endgroup

@group user_actions.json
@endpoint GET /user_actions.json
@required {offset: int, username: str, filter: str}
@returns(200) {user_actions: [map]}

@endgroup

@group session
@endpoint POST /session/forgot_password.json
@required {login: str}
@returns(200) {success: str, user_found: bool}

@endgroup

@group users
@endpoint PUT /users/password-reset/{token}.json
@required {token: str, username: str, password: str}
@returns(200)

@endgroup

@group u
@endpoint GET /u/{username}/emails.json
@required {username: str}
@returns(200) {email: str, secondary_emails: [any], unconfirmed_emails: [any], associated_accounts: [any]}

@endgroup

@end