Discourse API
Overview
This is the very first draft of the API Documentation and should be considered v0.0.1. Most likely the format and the content will change as progress is made. But the most important thing is that we have something to start with to improve upon.
This document should not be considered complete.
Current Version
Currently the API is not versioned (v1, v2, etc.). This will change at some point in the future, but could be a while.
https://meta.discourse.org/t/improving-discourse-api/9276/5
Consuming the API
You can consume the API using cURL commands, but we recommend using the discourse_api gem so that you can use Ruby.
https://meta.discourse.org/t/using-the-discourse-api-ruby-gem/17587
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 as a url parameter like this:
curl http://localhost:3000/c/test/sub-test.json?api_key=test_d7fd0429940&api_username=test_user
Categories
Get a list of categories
GET /categories.json
Example
curl http://localhost:3000/categories.json
List topics in a specific category
GET /c/:id.json
Example
curl http://localhost:3000/c/14.json
List the latest topics in a specific category
GET /c/:id/l/latest.json
Example
curl http://localhost:3000/c/14/l/latest.json
List new topics in a specific category
GET /c/:id/l/new.json
Example
curl http://localhost:3000/c/14/l/new.json
List the top topics in a specific category
GET /c/:id/l/top.json
Example
curl http://localhost:3000/c/14/l/top.json
List the topics in a sub-category
GET /c/:parent_id/:id.json
Example
curl http://localhost:3000/c/12/14.json
Create a category
POST /categories
Parameters
- name
- color
- text_color
Example
curl -X POST --data "name=bugs&color=3c3945&text_color=ffffff" http://localhost:3000/categories?api_key=test_d7fd0429940&api_username=test_user
Topics
Get the latest topics
GET /latest.json
Example
curl http://localhost:3000/latest.json
Get a the top topics
GET /top.json
Example
curl http://localhost:3000/top.json
Get a single topic
GET /t/:id.json
Example
curl http://localhost:3000/t/14.json
Create Topic
POST /posts
Parameters
- title
- raw
Example
curl -X POST -d title="Title of my topic" -d raw="This is the body of my topic" http://localhost:3000/posts?api_key=test_d7fd0429940&api_username=test_user
Update Topic
PUT /t/:id
Parameters
- topic_id
- title
- category_id
Example
curl -X PUT -d topic_id=14 -d title="This is my new title" http://localhost:3000/t/14?api_key=test_d7fd0429940&api_username=test_user
Posts
Create a post
POST /posts
Parameters
- topic_id
- raw
Example
curl -X POST -d topic_id=14 -d raw="This is a post to a topic." http://localhost:3000/posts?api_key=test_d7fd0429940&api_username=test_user
Users
Get info about a single user
GET /users/:username.json
Example
curl http://localhost:3000/users/steve.json
Update username
PUT /users/:username/preferences/username
Parameters
- new_username
Example
curl -X PUT -d new_username=steve http://localhost:3000/users/bart/preferences/username?api_key=test_d7fd0429940&api_username=test_user
Update email
PUT /users/:username/preferences/email
Parameters
Example
curl -X PUT -d [email protected] http://localhost:3000/users/steve/preferences/email?api_key=test_d7fd0429940&api_username=test_user
Update Custom Field
PUT /users/:username.json
Parameters
- user_fields[:field_id]
Example
curl -X PUT -d 'user_fields[1]=Lorem ipsum' http://localhost:3000/users/steve.json?api_key=test_d7fd0429940&api_username=test_user
Update trust level
PUT /admin/users/:user_id/trust_level
Parameters
- user_id
- level
Example
curl -X PUT -d user_id=102 -d level=2 http://localhost:3000/admin/users/102/trust_level?api_key=test_d7fd0429940&api_username=test_user
Create a user
POST /users
Parameters
- name
- username
- password
- active
Example
curl -X POST --data "[email protected]&password=P@ssword&active=true" http://localhost:3000/users?api_key=test_d7fd0429940&api_username=test_user
List a User’s recent activity
GET /user_actions.json
Parameters
- username
- filter
The filter
parameter takes a comma-separated list of integers to specify what type of activity to bring back. At the time of writing, the list was something like (grabbed from User Action Model):
LIKE = 1
WAS_LIKED = 2
BOOKMARK = 3
NEW_TOPIC = 4
REPLY = 5
RESPONSE = 6
MENTION = 7
QUOTE = 9
EDIT = 11
NEW_PRIVATE_MESSAGE = 12
GOT_PRIVATE_MESSAGE = 13
PENDING = 14
Example
curl http://localhost:3000/user_actions.json?username=test_user&filter=4,5,6,7,9&api_key=test_d7fd0429940&api_username=test_user
Badges
List badges
GET /admin/badges.json
Example
curl http://localhost:3000/admin/badges.json?api_key=test_d7fd0429940&api_username=test_user
Grant a badge to user
POST /user_badges
Parameters
- username
- badge_id
Example
curl -X POST -d username=john -d badge_id=101 http://localhost:3000/user_badges?api_key=test_d7fd0429940&api_username=test_user
Notifications
List your notifications
GET /notifications.json
Example
curl http://localhost:3000/notifications.json?api_key=test_d7fd0429940&api_username=test_user
mark notifications read
PUT /notifications/mark-read.json
Example
curl http://localhost:3000/notifications/mark-read.json?api_key=test_d7fd0429940&api_username=test_user
selectively mark notifications read
POST /topics/timings.json
POST Body = topic_id=1234&topic_time=1234&timings[X]=1234
Where X = post_number to mark read
note: this accepts multiple posts (based on comment a user is viewing) eg.
curl -X POST -d topic_id=1234 -d topic_time=1234 -d timings[1]=1234 -d timings[2]=1234 -d timings[3]=1234 http://localhost:3000 /topics/timings.json?api_key=test_d7fd0429940&api_username=test_user
will mark comments 1, 2 and 3 read on the topic 1234
Private Messages
List private messages
GET /topics/private-messages/:username.json
Example
curl http://localhost:3000/topics/private-messages/steve.json?api_key=test_d7fd0429940&api_username=test_user
Search
Search for a given query string
GET /search
Parameters
- q
- order
- ascending
where q
is search query.
Values for the order
parameter (there may be others, see below):
- category
- posts
- views
- activity
Examples
curl -X GET -d q="new quotes category" http://localhost:3000/search.json
Search for foo bar
and return results sorted by number of replies from least to most:
curl -X GET -d q="foo bar" -d order="posts" -d "ascending=true" http://localhost:3000/search.json
Parameters, and values for these parameters, can be determined from the Discourse search page: https://meta.discourse.org/search.
Files
Upload Image from URL
POST /uploads
Parameters
- username
- type
- url
- synchronous
Example
curl -X POST -d username="john" -d type="image" -d url="http://i.imgur.com/2toPGdS.jpg" -d synchronous="true" "http://localhost:3000/uploads?api_key=SOMETHING&api_username=SOMEONE"
Upload Image from File
POST /uploads
Parameters
- username
- type
- file
- synchronous
Example
curl -X POST -F username="john" -F type="image" -F file="@image.png" -F synchronous="true" "http://localhost:3000/uploads?api_key=SOMETHING&api_username=SOMEONE"
Groups
Create a group
curl -X POST --data "name=GROUPNAME&alias_level=0&visible=true&automatic_membership_retroactive=false&title=GROUPTITLE&primary_group=false" http://localhost:4000/admin/groups?api_key=SOMETHING&api_username=SOMEONE
Here are the parameters you can set:
- alias_level: 0
- automatic: false
- automatic_membership_email_domains: “”
- automatic_membership_retroactive: false
- grant_trust_level: 1
- name: “NAME”
- primary_group: false
- title: “TITLE”
- visible: true
Source: https://meta.discourse.org/t/discourse-api-documentation/22706