Discourse Users API
The Users API from Discourse — 23 operation(s) for users.
OpenAPI Specification
openapi: 3.1.0
info:
title: Discourse API Documentation Admin Users API
x-logo:
url: https://docs.discourse.org/logo.svg
version: latest
description: 'This page contains the documentation on how to use Discourse through API calls.
> Note: For any endpoints not listed you can follow the
[reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)
guide to figure out how to use an API endpoint.
### Request Content-Type
The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,
`multipart/form-data`, or `application/json`.
### Endpoint Names and Response Content-Type
Most API endpoints provide the same content as their HTML counterparts. For example
the URL `/categories` serves a list of categories, the `/categories.json` API provides the
same information in JSON format.
Instead of sending API requests to `/categories.json` you may also send them to `/categories`
and add an `Accept: application/json` header to the request to get the JSON response.
Sending requests with the `Accept` header is necessary if you want to use URLs
for related endpoints returned by the API, such as pagination URLs.
These URLs are returned without the `.json` prefix so you need to add the header in
order to get the correct response format.
### Authentication
Some endpoints do not require any authentication, pretty much anything else will
require you to be authenticated.
To become authenticated you will need to create an API Key from the admin panel.
Once you have your API Key you can pass it in along with your API Username
as an HTTP header like this:
```
curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system"
```
and this is how POST requests will look:
```
curl -X POST "http://127.0.0.1:3000/categories" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system" \
-F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
-F "color=49d9e9" \
-F "text_color=f0fcfd"
```
### Boolean values
If an endpoint accepts a boolean be sure to specify it as a lowercase
`true` or `false` value unless noted otherwise.
'
license:
name: MIT
url: https://docs.discourse.org/LICENSE.txt
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: discourse.example.com
tags:
- name: Users
paths:
/user-badges/{username}.json:
get:
summary: List badges for a user
tags:
- 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 admin api key in the request
header or it will be ignored'
approved:
type: boolean
user_fields:
type: object
additionalProperties: true
properties:
'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 with primary group 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_ignore_users:
type: boolean
can_mute_user:
type: boolean
can_mute_users:
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:
- integer
- 'null'
primary_group_name:
type:
- string
- 'null'
flair_group_id:
type:
- integer
- '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:
- integer
- '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
topic_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'
user_passkeys:
type: array
sidebar_tags:
type: array
sidebar_category_ids:
type: array
display_sidebar_tags:
type: boolean
can_pick_theme_with_custom_homepage:
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_smart_lists:
type: boolean
enable_markdown_monospace_font:
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
notify_on_linked_posts:
type: boolean
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
hide_profile:
type: boolean
hide_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
seen_popups:
type:
- array
- 'null'
topics_unread_when_closed:
type: boolean
composition_mode:
type: integer
interface_color_mode:
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/discourse/refs/heads/main/openapi/discourse-users-api-openapi.yml