Discourse Private Messages API
The Private Messages API from Discourse — 3 operation(s) for private messages.
OpenAPI Specification
openapi: 3.1.0
info:
title: Discourse API Documentation Admin Private Messages 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: Private Messages
paths:
/posts.json:
post:
summary: Creates a new topic, a new post, or a private message
tags:
- 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
posts_count:
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
- '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:
- integer
- 'null'
badges_granted:
type: array
items: {}
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:
- integer
- 'null'
reviewable_score_count:
type: integer
reviewable_score_pending_count:
type: integer
post_url:
type: string
post_localizations:
type: array
items: {}
mentioned_users:
type: array
items: {}
required:
- id
- name
- username
- avatar_template
- created_at
- cooked
- post_number
- post_type
- posts_count
- 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
- post_url
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.'
auto_track:
type: boolean
description: 'If false, the user will not track the topic. By default,
the user will track the topic.'
required:
- raw
/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:
- integer
- 'null'
participants:
type: array
items:
type: object
properties:
extras:
type: string
description:
type:
- string
- 'null'
user_id:
type: integer
primary_group_id:
type:
- integer
- '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:
- integer
- 'null'
participants:
type: array
items: {}