The Discourse API exposes the full set of REST endpoints used to manage a Discourse forum, including categories, topics, posts, users, groups, tags, badges, uploads, search, site settings, and admin operations. Authentication uses an API Key plus an Api-Username header issued from the Discourse admin panel.
{
"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.\n\n> Note: For any endpoints not listed you can follow the\n[reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)\nguide to figure out how to use an API endpoint.\n\n### Request Content-Type\n\nThe Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,\n`multipart/form-data`, or `application/json`.\n\n### Endpoint Names and Response Content-Type\n\nMost API endpoints provide the same content as their HTML counterparts. For example\nthe URL `/categories` serves a list of categories, the `/categories.json` API provides the\nsame information in JSON format.\n\nInstead of sending API requests to `/categories.json` you may also send them to `/categories`\nand add an `Accept: application/json` header to the request to get the JSON response.\nSending requests with the `Accept` header is necessary if you want to use URLs\nfor related endpoints returned by the API, such as pagination URLs.\nThese URLs are returned without the `.json` prefix so you need to add the header in\norder to get the correct response format.\n\n### Authentication\n\nSome endpoints do not require any authentication, pretty much anything else will\nrequire you to be authenticated.\n\nTo become authenticated you will need to create an API Key from the admin panel.\n\nOnce you have your API Key you can pass it in along with your API Username\nas an HTTP header like this:\n\n```\ncurl -X GET \"http://127.0.0.1:3000/admin/users/list/active.json\" \\\n-H \"Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19\" \\\n-H \"Api-Username: system\"\n```\n\nand this is how POST requests will look:\n\n```\ncurl -X POST \"http://127.0.0.1:3000/categories\" \\\n-H \"Content-Type: multipart/form-data;\" \\\n-H \"Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19\" \\\n-H \"Api-Username: system\" \\\n-F \"name=89853c20-4409-e91a-a8ea-f6cdff96aaaa\" \\\n-F \"color=49d9e9\" \\\n-F \"text_color=f0fcfd\"\n```\n\n### Boolean values\n\nIf an endpoint accepts a boolean be sure to specify it as a lowercase\n`true` or `false` value unless noted otherwise.\n",
"license": {
"name": "MIT",
"url": "https://docs.discourse.org/LICENSE.txt"
}
},
"paths": {
"/discourse-post-event/events.json": {
"get": {
"summary": "List calendar events",
"tags": [
"Discourse Calendar - Events"
],
"operationId": "listEvents",
"parameters": [
{
"name": "include_details",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"description": "Include detailed event information (creator, invitees, stats,\netc.)"
},
{
"name": "category_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Filter events by category ID"
},
{
"name": "include_subcategories",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"description": "Include events from subcategories when filtering by category"
},
{
"name": "post_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Filter to events associated with a specific post ID"
},
{
"name": "attending_user",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter to events where the specified user (username) has RSVP'd\nas going"
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Return events starting before this date/time (ISO 8601 format)"
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Return events starting after this date/time (ISO 8601 format)"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort order for events by start date (default: asc)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"description": "Maximum number of events to return (default: 200)"
}
],
"responses": {
"200": {
"description": "success response (detailed)",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"category_id": {
"type": [
"integer",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"recurrence": {
"type": [
"string",
"null"
]
},
"recurrence_until": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"starts_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"ends_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"rrule": {
"type": "string"
},
"show_local_time": {
"type": "boolean"
},
"timezone": {
"type": [
"string",
"null"
]
},
"duration": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}:\\d{2}$"
},
"all_day": {
"type": "boolean"
},
"post": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"post_number": {
"type": "integer"
},
"url": {
"type": "string"
},
"category_slug": {
"type": "string"
},
"topic": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"tags_descriptions": {
"type": "object"
}
},
"required": [
"id",
"title",
"tags",
"tags_descriptions"
]
}
},
"required": [
"id",
"post_number",
"url",
"category_slug",
"topic"
]
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"starts_at": {
"type": [
"string",
"null"
]
},
"ends_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"starts_at",
"ends_at"
]
}
},
"can_act_on_discourse_post_event": {
"type": [
"boolean",
"null"
]
},
"can_update_attendance": {
"type": [
"boolean",
"null"
]
},
"creator": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"avatar_template": {
"type": "string"
}
},
"required": [
"id",
"username",
"avatar_template"
]
},
"custom_fields": {
"type": [
"object",
"null"
]
},
"is_closed": {
"type": "boolean"
},
"is_expired": {
"type": "boolean"
},
"is_ongoing": {
"type": "boolean"
},
"is_private": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"is_standalone": {
"type": "boolean"
},
"minimal": {
"type": [
"boolean",
"null"
]
},
"raw_invitees": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"reminders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"unit": {
"type": "string"
},
"period": {
"type": "string",
"enum": [
"before",
"after"
]
},
"type": {
"type": "string"
}
},
"required": [
"value",
"unit",
"period",
"type"
]
}
},
"sample_invitees": {
"type": "array",
"items": {
"type": "object"
}
},
"should_display_invitees": {
"type": "boolean"
},
"stats": {
"type": "object"
},
"status": {
"type": "string",
"enum": [
"public",
"private",
"standalone"
]
},
"url": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"location": {
"type": [
"string",
"null"
]
},
"watching_invitee": {
"type": [
"object",
"null"
]
},
"chat_enabled": {
"type": [
"boolean",
"null"
]
},
"channel": {
"type": "object"
},
"max_attendees": {
"type": [
"integer",
"null"
]
},
"at_capacity": {
"type": "boolean"
}
},
"required": [
"id",
"category_id",
"starts_at",
"ends_at",
"show_local_time",
"timezone",
"can_act_on_discourse_post_event",
"can_update_attendance",
"is_closed",
"is_expired",
"is_ongoing",
"is_private",
"is_public",
"is_standalone",
"should_display_invitees",
"status",
"at_capacity",
"post",
"occurrences"
]
}
}
},
"required": [
"events"
]
}
}
}
}
}
}
},
"/discourse-post-event/events.ics": {
"get": {
"summary": "Export calendar events in iCalendar format",
"tags": [
"Discourse Calendar - Events"
],
"operationId": "exportEventsICS",
"parameters": [
{
"name": "category_id",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Filter events by category ID"
},
{
"name": "include_subcategories",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"description": "Include events from subcategories when filtering by category"
},
{
"name": "attending_user",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter to events where the specified user (username) has RSVP'd\nas going"
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Return events starting before this date/time (ISO 8601 format)"
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Return events starting after this date/time (ISO 8601 format)"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort order for events by start date (default: asc)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"description": "Maximum number of events to return (default: 200)"
}
],
"responses": {
"200": {
"description": "iCalendar file",
"content": {
"text/calendar": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/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"
]
},
"image_upload_id": {
"type": [
"integer",
"null"
]
},
"badge_type_id": {
"type": "integer"
},
"show_in_post_header": {
"type": "boolean"
}
},
"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",
"image_upload_id",
"show_in_post_header"
]
}
},
"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": {
# --- truncated at 32 KB (668 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/discourse/refs/heads/main/openapi/discourse-openapi.json