Discourse API Documentation
This page contains the documentation on how to use Discourse through API calls
COMMUNITYNO AUTH0 INSTALLS
OpenAPI Specificationv3.1
{
"openapi": "3.1.0",
"servers": [
{
"url": "http://discourse.local"
},
{
"url": "https://{defaultHost}",
"variables": {
"defaultHost": {
"default": "discourse.example.com"
}
}
}
],
"info": {
"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"
},
"title": "Discourse API Documentation",
"version": "latest",
"x-apisguru-categories": [
"social"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_docs.discourse.org_logo.svg"
},
"x-origin": [
{
"format": "openapi",
"url": "http://docs.discourse.org/openapi.json",
"version": "3.1"
}
],
"x-providerName": "discourse.local"
},
"paths": {
"/admin/backups.json": {
"get": {
"operationId": "getBackups",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"filename": {
"type": "string"
},
"last_modified": {
"type": "string"
},
"size": {
"type": "integer"
}
},
"required": [
"filename",
"size",
"last_modified"
],
"type": "object"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
}
},
"description": "success response"
}
},
"summary": "List backups",
"tags": [
"Backups"
]
},
"post": {
"operationId": "createBackup",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"with_uploads": {
"type": "boolean"
}
},
"required": [
"with_uploads"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"required": [
"success"
]
}
}
},
"description": "success response"
}
},
"summary": "Create backup",
"tags": [
"Backups"
]
}
},
"/admin/backups/{filename}": {
"get": {
"operationId": "downloadBackup",
"parameters": [
{
"in": "path",
"name": "filename",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "success response"
}
},
"summary": "Download backup",
"tags": [
"Backups"
]
},
"put": {
"operationId": "sendDownloadBackupEmail",
"parameters": [
{
"in": "path",
"name": "filename",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "success response"
}
},
"summary": "Send download backup email",
"tags": [
"Backups"
]
}
},
"/admin/badges.json": {
"get": {
"operationId": "adminListBadges",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"admin_badges": {
"additionalProperties": false,
"properties": {
"badge_grouping_ids": {
"items": {},
"type": "array"
},
"badge_ids": {
"items": {},
"type": "array"
},
"badge_type_ids": {
"items": {},
"type": "array"
},
"protected_system_fields": {
"items": {},
"type": "array"
},
"triggers": {
"additionalProperties": false,
"properties": {
"none": {
"type": "integer"
},
"post_action": {
"type": "integer"
},
"post_revision": {
"type": "integer"
},
"trust_level_change": {
"type": "integer"
},
"user_change": {
"type": "integer"
}
},
"required": [
"user_change",
"none",
"post_revision",
"trust_level_change",
"post_action"
],
"type": "object"
}
},
"required": [
"protected_system_fields",
"triggers",
"badge_ids",
"badge_grouping_ids",
"badge_type_ids"
],
"type": "object"
},
"badge_groupings": {
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"position": {
"type": "integer"
},
"system": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"description",
"position",
"system"
],
"type": "object"
},
"type": "array"
},
"badge_types": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"sort_order": {
"type": "integer"
}
},
"required": [
"id",
"name",
"sort_order"
],
"type": "object"
},
"type": "array"
},
"badges": {
"items": {
"additionalProperties": false,
"properties": {
"allow_title": {
"type": "boolean"
},
"auto_revoke": {
"type": "boolean"
},
"badge_grouping_id": {
"type": "integer"
},
"badge_type_id": {
"type": "integer"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"grant_count": {
"type": "integer"
},
"i18n_name": {
"type": [
"string",
"null"
]
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"listable": {
"type": "boolean"
},
"long_description": {
"type": "string"
},
"manually_grantable": {
"type": "boolean"
},
"multiple_grant": {
"type": "boolean"
},
"name": {
"type": "string"
},
"query": {
"type": [
"string",
"null"
]
},
"show_posts": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"system": {
"type": "boolean"
},
"target_posts": {
"type": "boolean"
},
"trigger": {
"type": [
"integer",
"null"
]
}
},
"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"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"badges",
"badge_types",
"badge_groupings",
"admin_badges"
]
}
}
},
"description": "success response"
}
},
"summary": "List badges",
"tags": [
"Badges"
]
},
"post": {
"operationId": "createBadge",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"badge_type_id": {
"description": "The ID for the badge type. 1 for Gold, 2 for Silver,\n3 for Bronze.",
"type": "integer"
},
"name": {
"description": "The name for the new badge.",
"type": "string"
}
},
"required": [
"name",
"badge_type_id"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"badge": {
"additionalProperties": false,
"properties": {
"allow_title": {
"type": "boolean"
},
"auto_revoke": {
"type": "boolean"
},
"badge_grouping_id": {
"type": "integer"
},
"badge_type_id": {
"type": "integer"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"grant_count": {
"type": "integer"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"listable": {
"type": "boolean"
},
"long_description": {
"type": "string"
},
"manually_grantable": {
"type": "boolean"
},
"multiple_grant": {
"type": "boolean"
},
"name": {
"type": "string"
},
"query": {
"type": [
"string",
"null"
]
},
"show_posts": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"system": {
"type": "boolean"
},
"target_posts": {
"type": "boolean"
},
"trigger": {
"type": [
"string",
"null"
]
}
},
"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"
],
"type": "object"
},
"badge_types": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"sort_order": {
"type": "integer"
}
},
"required": [
"id",
"name",
"sort_order"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"badge_types",
"badge"
]
}
}
},
"description": "success response"
}
},
"summary": "Create badge",
"tags": [
"Badges"
]
}
},
"/admin/badges/{id}.json": {
"delete": {
"operationId": "deleteBadge",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "success response"
}
},
"summary": "Delete badge",
"tags": [
"Badges"
]
},
"put": {
"operationId": "updateBadge",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"badge_type_id": {
"description": "The ID for the badge type. 1 for Gold, 2 for Silver,\n3 for Bronze.",
"type": "integer"
},
"name": {
"description": "The name for the new badge.",
"type": "string"
}
},
"required": [
"name",
"badge_type_id"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"badge": {
"additionalProperties": false,
"properties": {
"allow_title": {
"type": "boolean"
},
"auto_revoke": {
"type": "boolean"
},
"badge_grouping_id": {
"type": "integer"
},
"badge_type_id": {
"type": "integer"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"grant_count": {
"type": "integer"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"listable": {
"type": "boolean"
},
"long_description": {
"type": "string"
},
"manually_grantable": {
"type": "boolean"
},
"multiple_grant": {
"type": "boolean"
},
"name": {
"type": "string"
},
"query": {
"type": [
"string",
"null"
]
},
"show_posts": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"system": {
"type": "boolean"
},
"target_posts": {
"type": "boolean"
},
"trigger": {
"type": [
"string",
"null"
]
}
},
"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"
],
"type": "object"
},
"badge_types": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"sort_order": {
"type": "integer"
}
},
"required": [
"id",
"name",
"sort_order"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"badge_types",
"badge"
]
}
}
},
"description": "success response"
}
},
"summary": "Update badge",
"tags": [
"Badges"
]
}
},
"/admin/groups.json": {
"post": {
"operationId": "createGroup",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"group": {
"additionalProperties": false,
"properties": {
"automatic_membership_email_domains": {
"description": "pipe|separated",
"type": "string"
},
"bio_raw": {
"description": "About Group",
"type": "string"
},
"default_notification_level": {
"type": "integer"
},
"flair_bg_color": {
"type": "string"
},
"flair_icon": {
"type": "string"
},
"flair_upload_id": {
"type": "integer"
},
"full_name": {
"type": "string"
},
"muted_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"name": {
"type": "string"
},
"owner_usernames": {
"description": "comma,separated",
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"regular_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"tracking_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"usernames": {
"description": "comma,separated",
"type": "string"
},
"visibility_level": {
"type": "integer"
},
"watching_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"watching_first_post_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"group"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"basic_group": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_edit_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"required": [
"id",
"automatic",
"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"
],
"type": "object"
}
},
"required": [
"basic_group"
]
}
}
},
"description": "group created"
}
},
"summary": "Create a group",
"tags": [
"Groups"
]
}
},
"/admin/groups/{id}.json": {
"delete": {
"operationId": "deleteGroup",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"required": [
"success"
]
}
}
},
"description": "response"
}
},
"summary": "Delete a group",
"tags": [
"Groups"
]
}
},
"/admin/users/list/{flag}.json": {
"get": {
"operationId": "adminListUsers",
"parameters": [
{
"in": "path",
"name": "flag",
"required": true,
"schema": {
"enum": [
"active",
"new",
"staff",
"suspended",
"blocked",
"suspect"
],
"type": "string"
}
},
{
"in": "query",
"name": "order",
"schema": {
"enum": [
"created",
"last_emailed",
"seen",
"username",
"email",
"trust_level",
"days_visited",
"posts_read",
"topics_viewed",
"posts",
"read_time"
],
"type": "string"
}
},
{
"in": "query",
"name": "asc",
"schema": {
"enum": [
"true"
],
"type": "string"
}
},
{
"in": "query",
"name": "page",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "show_emails",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"active": {
"type": "boolean"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"created_at": {
"type": "string"
},
"created_at_age": {
"type": [
"number",
"null"
]
},
"days_visited": {
"type": "integer"
},
"email": {
"type": "string"
},
"flag_level": {
"type": "integer"
},
"id": {
"type": "integer"
},
"last_emailed_age": {
"type": [
"number",
"null"
]
},
"last_emailed_at": {
"type": [
"string",
"null"
]
},
"last_seen_age": {
"type": [
"number",
"null"
]
},
"last_seen_at": {
"type": [
"string",
"null"
]
},
"manual_locked_trust_level": {
"type": [
"string",
"null"
]
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_count": {
"type": "integer"
},
"posts_read_count": {
"type": "integer"
},
"secondary_emails": {
"items": {},
"type": "array"
},
"staged": {
"type": "boolean"
},
"time_read": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"topics_entered": {
"type": "integer"
},
"trust_level": {
"type": "integer"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"active",
"admin",
"moderator",
"last_seen_at",
"last_emailed_at",
"created_at",
"last_seen_age",
"last_emailed_age",
"created_at_age",
"trust_level",
"manual_locked_trust_level",
"flag_level",
"title",
"time_read",
"staged",
"days_visited",
"posts_read_count",
"topics_entered",
"post_count"
],
"type": "object"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
}
},
"description": "response"
}
},
"summary": "Get a list of users",
"tags": [
"Users",
"Admin"
]
}
},
"/admin/users/{id}.json": {
"delete": {
"operationId": "deleteUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"block_email": {
"type": "boolean"
},
"block_ip": {
"type": "boolean"
},
"block_urls": {
"type": "boolean"
},
"delete_posts": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"deleted": {
"type": "boolean"
}
},
"required": [
"deleted"
]
}
}
},
"description": "response"
}
},
"summary": "Delete a user",
"tags": [
"Users",
"Admin"
]
},
"get": {
"operationId": "adminGetUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"active": {
"type": "boolean"
},
"admin": {
"type": "boolean"
},
"api_key_count": {
"type": "integer"
},
"approved_by": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": [
"object",
"null"
]
},
"associated_accounts": {
"items": {},
"type": "array"
},
"avatar_template": {
"type": "string"
},
"badge_count": {
"type": "integer"
},
"bounce_score": {
"type": [
"integer",
"null"
]
},
"can_activate": {
"type": "boolean"
},
"can_be_anonymized": {
"type": "boolean"
},
"can_be_deleted": {
"type": "boolean"
},
"can_be_merged": {
"type": "boolean"
},
"can_deactivate": {
"type": "boolean"
},
"can_delete_all_posts": {
"type": "boolean"
},
"can_delete_sso_record": {
"type": "boolean"
},
"can_disable_second_factor": {
"type": "boolean"
},
"can_grant_admin": {
"type": "boolean"
},
"can_grant_moderation": {
"type": "boolean"
},
"can_impersonate": {
"type": "boolean"
},
"can_revoke_admin": {
"type": "boolean"
},
"can_revoke_moderation": {
"type": "boolean"
},
"can_send_activation_email": {
"type": "boolean"
},
"can_view_action_logs": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"created_at_age": {
"type": [
"number",
"null"
]
},
"days_visited": {
"type": "integer"
},
"external_ids": {
"type": "object"
},
"flag_level": {
"type": "integer"
},
"flags_given_count": {
"type": "integer"
},
"flags_received_count": {
"type": "integer"
},
"full_suspend_reason": {
"type": [
"string",
"null"
]
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"id": {
"type": "integer"
},
"ip_address": {
"type": "string"
},
"last_emailed_age": {
"type": [
"number",
"null"
]
},
"last_emailed_at": {
"type": [
"string",
"null"
]
},
"last_seen_age": {
"type": [
"number",
"null"
]
},
"last_seen_at": {
"type": [
"string",
"null"
]
},
"like_count": {
"type": "integer"
},
"like_given_count": {
"type": "integer"
},
"manual_locked_trust_level": {
"type": [
"string",
"null"
]
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"next_penalty": {
"type": "string"
},
"penalty_counts": {
"additionalProperties": false,
"properties": {
"silenced": {
"type": "integer"
},
"suspended": {
"type": "integer"
}
},
"required": [
"silenced",
"suspended"
],
"type": "object"
},
"post_count": {
"type": "integer"
},
"post_edits_count": {
"type": [
"integer",
"null"
]
},
"posts_read_count": {
"type": "integer"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"private_topics_count": {
"type": "integer"
},
"registration_ip_address": {
"type": [
"string",
"null"
]
},
"reset_bounce_score_after": {
"type": [
"string",
"null"
]
},
"silence_reason": {
"type": [
"string",
"null"
]
},
"silenced_by": {
"type": [
"string",
"null"
]
},
"single_sign_on_record": {
"type": [
"string",
"null"
]
},
"staged": {
"type": "boolean"
},
"suspended_by": {
"type": [
"string",
"null"
]
},
"time_read": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"tl3_requirements": {
"additionalProperties": false,
"properties": {
"days_visited": {
"type": "integer"
},
"max_flagged_by_users": {
"type": "integer"
},
"max_flagged_posts": {
"type": "integer"
},
"min_days_visited": {
"type": "integer"
},
"min_likes_given": {
"type": "integer"
},
"min_likes_received": {
"type": "integer"
},
"min_likes_received_days": {
"type": "integer"
},
"min_likes_received_users": {
"type": "integer"
},
"min_posts_read": {
"type": "integer"
},
"min_posts_read_all_time": {
"type": "integer"
},
"min_topics_replied_to": {
"type": "integer"
},
"min_topics_viewed": {
"type": "integer"
},
"min_topics_viewed_all_time": {
"type": "integer"
},
"num_flagged_by_users": {
"type": "integer"
},
"num_flagged_posts": {
"type": "integer"
},
"num_likes_given": {
"type": "integer"
},
"num_likes_received": {
"type": "integer"
},
"num_likes_received_days": {
"type": "integer"
},
"num_likes_received_users": {
"type": "integer"
},
"num_topics_replied_to": {
"type": "integer"
},
"on_grace_period": {
"type": "boolean"
},
"penalty_counts": {
"additionalProperties": false,
"properties": {
"silenced": {
"type": "integer"
},
"suspended": {
"type": "integer"
},
"total": {
"type": "integer"
}
},
"required": [
"silenced",
"suspended",
"total"
],
"type": "object"
},
"posts_read": {
"type": "integer"
},
"posts_read_all_time": {
"type": "integer"
},
"requirements_lost": {
"type": "boolean"
},
"requirements_met": {
"type": "boolean"
},
"time_period": {
"type": "integer"
},
"topics_viewed": {
"type": "integer"
},
"topics_viewed_all_time": {
"type": "integer"
},
"trust_level_locked": {
"type": "boolean"
}
},
"required": [
"time_period",
"requirements_met",
"requirements_lost",
"trust_level_locked",
"on_grace_period",
"days_visited",
"min_days_visited",
"num_topics_replied_to",
"min_topics_replied_to",
"topics_viewed",
"min_topics_viewed",
"posts_read",
"min_posts_read",
"topics_viewed_all_time",
"min_topics_viewed_all_time",
"posts_read_all_time",
"min_posts_read_all_time",
"num_flagged_posts",
"max_flagged_posts",
"num_flagged_by_users",
"max_flagged_by_users",
"num_likes_given",
"min_likes_given",
"num_likes_received",
"min_likes_received",
"num_likes_received_days",
"min_likes_received_days",
"num_likes_received_users",
"min_likes_received_users",
"penalty_counts"
],
"type": "object"
},
"topic_count": {
"type": "integer"
},
"topics_entered": {
"type": "integer"
},
"trust_level": {
"type": "integer"
},
"username": {
"type": "string"
},
"warnings_received_count": {
"type": "integer"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"active",
"admin",
"moderator",
"last_seen_at",
"last_emailed_at",
"created_at",
"last_seen_age",
"last_emailed_age",
"created_at_age",
"trust_level",
"manual_locked_trust_level",
"flag_level",
"title",
"time_read",
"staged",
"days_visited",
"posts_read_count",
"topics_entered",
"post_count",
"can_send_activation_email",
"can_activate",
"can_deactivate",
"ip_address",
"registration_ip_address",
"can_grant_admin",
"can_revoke_admin",
"can_grant_moderation",
"can_revoke_moderation",
"can_impersonate",
"like_count",
"like_given_count",
"topic_count",
"flags_given_count",
"flags_received_count",
"private_topics_count",
"can_delete_all_posts",
"can_be_deleted",
"can_be_anonymized",
"can_be_merged",
"full_suspend_reason",
"silence_reason",
"primary_group_id",
"badge_count",
"warnings_received_count",
"bounce_score",
"reset_bounce_score_after",
"can_view_action_logs",
"can_disable_second_factor",
"can_delete_sso_record",
"api_key_count",
"single_sign_on_record",
"approved_by",
"suspended_by",
"silenced_by",
"groups",
"external_ids"
]
}
}
},
"description": "response"
}
},
"summary": "Get a user by id",
"tags": [
"Users",
"Admin"
]
}
},
"/admin/users/{id}/anonymize.json": {
"put": {
"operationId": "anonymizeUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"success",
"username"
]
}
}
},
"description": "response"
}
},
"summary": "Anonymize a user",
"tags": [
"Users",
"Admin"
]
}
},
"/admin/users/{id}/log_out.json": {
"post": {
"operationId": "logOutUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"required": [
"success"
]
}
}
},
"description": "response"
}
},
"summary": "Log a user out",
"tags": [
"Users",
"Admin"
]
}
},
"/admin/users/{id}/silence.json": {
"put": {
"operationId": "silenceUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"message": {
"description": "Will send an email with this message when present",
"type": "string"
},
"post_action": {
"examples": [
"delete"
],
"type": "string"
},
"reason": {
"type": "string"
},
"silenced_till": {
"examples": [
"2022-06-01T08:00:00.000Z"
],
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"silence": {
"additionalProperties": false,
"properties": {
"silence_reason": {
"type": "string"
},
"silenced": {
"type": "boolean"
},
"silenced_at": {
"type": "string"
},
"silenced_by": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
},
"silenced_till": {
"type": "string"
}
},
"required": [
"silenced",
"silence_reason",
"silenced_till",
"silenced_at",
"silenced_by"
],
"type": "object"
}
},
"required": [
"silence"
]
}
}
},
"description": "response"
}
},
"summary": "Silence a user",
"tags": [
"Users",
"Admin"
]
}
},
"/admin/users/{id}/suspend.json": {
"put": {
"operationId": "suspendUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"message": {
"description": "Will send an email with this message when present",
"type": "string"
},
"post_action": {
"examples": [
"delete"
],
"type": "string"
},
"reason": {
"type": "string"
},
"suspend_until": {
"examples": [
"2121-02-22"
],
"type": "string"
}
},
"required": [
"suspend_until",
"reason"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"suspension": {
"additionalProperties": false,
"properties": {
"full_suspend_reason": {
"type": "string"
},
"suspend_reason": {
"type": "string"
},
"suspended_at": {
"type": "string"
},
"suspended_by": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
},
"suspended_till": {
"type": "string"
}
},
"required": [
"suspend_reason",
"full_suspend_reason",
"suspended_till",
"suspended_at",
"suspended_by"
],
"type": "object"
}
},
"required": [
"suspension"
]
}
}
},
"description": "response"
}
},
"summary": "Suspend a user",
"tags": [
"Users",
"Admin"
]
}
},
"/c/{id}/show.json": {
"get": {
"operationId": "getCategory",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"category": {
"additionalProperties": false,
"properties": {
"all_topics_wiki": {
"type": "boolean"
},
"allow_badges": {
"type": "boolean"
},
"allow_global_tags": {
"type": "boolean"
},
"allow_unlimited_owner_edits_on_first_post": {
"type": "boolean"
},
"allowed_tag_groups": {
"items": {},
"type": "array"
},
"allowed_tags": {
"items": {},
"type": "array"
},
"auto_close_based_on_last_post": {
"type": "boolean"
},
"auto_close_hours": {
"type": [
"string",
"null"
]
},
"available_groups": {
"items": {},
"type": "array"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"color": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"default_list_filter": {
"type": "string"
},
"default_slow_mode_seconds": {
"type": [
"string",
"null"
]
},
"default_top_period": {
"type": "string"
},
"default_view": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"description_excerpt": {
"type": [
"string",
"null"
]
},
"description_text": {
"type": [
"string",
"null"
]
},
"email_in": {
"type": [
"string",
"null"
]
},
"email_in_allow_strangers": {
"type": "boolean"
},
"form_template_ids": {
"items": {},
"type": "array"
},
"group_permissions": {
"items": {
"additionalProperties": false,
"properties": {
"group_name": {
"type": "string"
},
"permission_type": {
"type": "integer"
}
},
"required": [
"permission_type",
"group_name"
],
"type": "object"
},
"type": "array"
},
"has_children": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"mailinglist_mirror": {
"type": "boolean"
},
"minimum_required_tags": {
"type": "integer"
},
"name": {
"type": "string"
},
"navigate_to_first_post_after_read": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"num_featured_topics": {
"type": "integer"
},
"permission": {
"type": [
"integer",
"null"
]
},
"position": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"read_only_banner": {
"type": [
"string",
"null"
]
},
"read_restricted": {
"type": "boolean"
},
"required_tag_groups": {
"items": {
"additionalProperties": false,
"properties": {
"min_count": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"min_count"
],
"type": "object"
},
"type": "array"
},
"search_priority": {
"type": "integer"
},
"show_subcategory_list": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"sort_ascending": {
"type": [
"string",
"null"
]
},
"sort_order": {
"type": [
"string",
"null"
]
},
"subcategory_list_style": {
"type": "string"
},
"text_color": {
"type": "string"
},
"topic_count": {
"type": "integer"
},
"topic_featured_link_allowed": {
"type": "boolean"
},
"topic_template": {
"type": [
"string",
"null"
]
},
"topic_url": {
"type": [
"string",
"null"
]
},
"uploaded_background": {
"type": [
"string",
"null"
]
},
"uploaded_logo": {
"type": [
"string",
"null"
]
},
"uploaded_logo_dark": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"text_color",
"slug",
"topic_count",
"post_count",
"position",
"description",
"description_text",
"description_excerpt",
"topic_url",
"read_restricted",
"permission",
"notification_level",
"can_edit",
"topic_template",
"has_children",
"sort_order",
"sort_ascending",
"show_subcategory_list",
"num_featured_topics",
"default_view",
"subcategory_list_style",
"default_top_period",
"default_list_filter",
"minimum_required_tags",
"navigate_to_first_post_after_read",
"custom_fields",
"required_tag_groups",
"read_only_banner",
"available_groups",
"auto_close_hours",
"auto_close_based_on_last_post",
"allow_unlimited_owner_edits_on_first_post",
"default_slow_mode_seconds",
"group_permissions",
"email_in",
"email_in_allow_strangers",
"mailinglist_mirror",
"all_topics_wiki",
"can_delete",
"allow_badges",
"topic_featured_link_allowed",
"search_priority",
"uploaded_logo",
"uploaded_logo_dark",
"uploaded_background"
],
"type": "object"
}
},
"required": [
"category"
]
}
}
},
"description": "response"
}
},
"summary": "Show category",
"tags": [
"Categories"
]
}
},
"/c/{slug}/{id}.json": {
"get": {
"operationId": "listCategoryTopics",
"parameters": [
{
"in": "path",
"name": "slug",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"additionalProperties": false,
"properties": {
"can_create_topic": {
"type": "boolean"
},
"per_page": {
"type": "integer"
},
"top_tags": {
"items": {},
"type": "array"
},
"topics": {
"items": {
"additionalProperties": false,
"properties": {
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": [
"string",
"null"
]
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"excerpt": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": [
"string",
"null"
]
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"required": [
"extras",
"description",
"user_id",
"primary_group_id"
],
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"required": [
"id",
"title",
"fancy_title",
"slug",
"posts_count",
"reply_count",
"highest_post_number",
"image_url",
"created_at",
"last_posted_at",
"bumped",
"bumped_at",
"archetype",
"unseen",
"pinned",
"unpinned",
"excerpt",
"visible",
"closed",
"archived",
"bookmarked",
"liked",
"views",
"like_count",
"has_summary",
"last_poster_username",
"category_id",
"pinned_globally",
"featured_link",
"posters"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"can_create_topic",
"per_page",
"topics"
],
"type": "object"
},
"users": {
"items": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"topic_list"
]
}
}
},
"description": "success response"
}
},
"summary": "List topics",
"tags": [
"Categories"
]
}
},
"/categories.json": {
"get": {
"operationId": "listCategories",
"parameters": [
{
"in": "query",
"name": "include_subcategories",
"schema": {
"enum": [
true
],
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"category_list": {
"additionalProperties": false,
"properties": {
"can_create_category": {
"type": "boolean"
},
"can_create_topic": {
"type": "boolean"
},
"categories": {
"items": {
"additionalProperties": false,
"properties": {
"can_edit": {
"type": "boolean"
},
"color": {
"type": "string"
},
"default_list_filter": {
"type": "string"
},
"default_top_period": {
"type": "string"
},
"default_view": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"description_excerpt": {
"type": [
"string",
"null"
]
},
"description_text": {
"type": [
"string",
"null"
]
},
"has_children": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"is_uncategorized": {
"type": "boolean"
},
"minimum_required_tags": {
"type": "integer"
},
"name": {
"type": "string"
},
"navigate_to_first_post_after_read": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"num_featured_topics": {
"type": "integer"
},
"permission": {
"type": "integer"
},
"position": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"read_restricted": {
"type": "boolean"
},
"show_subcategory_list": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"sort_ascending": {
"type": [
"string",
"null"
]
},
"sort_order": {
"type": [
"string",
"null"
]
},
"subcategory_ids": {
"items": {},
"type": "array"
},
"subcategory_list": {
"items": {},
"type": [
"array",
"null"
]
},
"subcategory_list_style": {
"type": "string"
},
"text_color": {
"type": "string"
},
"topic_count": {
"type": "integer"
},
"topic_template": {
"type": [
"string",
"null"
]
},
"topic_url": {
"type": [
"string",
"null"
]
},
"topics_all_time": {
"type": "integer"
},
"topics_day": {
"type": "integer"
},
"topics_month": {
"type": "integer"
},
"topics_week": {
"type": "integer"
},
"topics_year": {
"type": "integer"
},
"uploaded_background": {
"type": [
"string",
"null"
]
},
"uploaded_logo": {
"type": [
"string",
"null"
]
},
"uploaded_logo_dark": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"text_color",
"slug",
"topic_count",
"post_count",
"position",
"description",
"description_text",
"description_excerpt",
"topic_url",
"read_restricted",
"permission",
"notification_level",
"can_edit",
"topic_template",
"has_children",
"sort_order",
"sort_ascending",
"show_subcategory_list",
"num_featured_topics",
"default_view",
"subcategory_list_style",
"default_top_period",
"default_list_filter",
"minimum_required_tags",
"navigate_to_first_post_after_read",
"topics_day",
"topics_week",
"topics_month",
"topics_year",
"topics_all_time",
"subcategory_ids",
"uploaded_logo",
"uploaded_logo_dark",
"uploaded_background"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"can_create_category",
"can_create_topic",
"categories"
],
"type": "object"
}
},
"required": [
"category_list"
]
}
}
},
"description": "success response"
}
},
"summary": "Retrieves a list of categories",
"tags": [
"Categories"
]
},
"post": {
"operationId": "createCategory",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"allow_badges": {
"type": "boolean"
},
"color": {
"examples": [
"49d9e9"
],
"type": "string"
},
"form_template_ids": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"parent_category_id": {
"type": "integer"
},
"permissions": {
"additionalProperties": true,
"properties": {
"everyone": {
"examples": [
1
],
"type": "integer"
},
"staff": {
"type": "integer"
}
},
"type": "object"
},
"search_priority": {
"type": "integer"
},
"slug": {
"type": "string"
},
"text_color": {
"examples": [
"f0fcfd"
],
"type": "string"
},
"topic_featured_links_allowed": {
"type": "boolean"
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"category": {
"additionalProperties": false,
"properties": {
"all_topics_wiki": {
"type": "boolean"
},
"allow_badges": {
"type": "boolean"
},
"allow_global_tags": {
"type": "boolean"
},
"allow_unlimited_owner_edits_on_first_post": {
"type": "boolean"
},
"allowed_tag_groups": {
"items": {},
"type": "array"
},
"allowed_tags": {
"items": {},
"type": "array"
},
"auto_close_based_on_last_post": {
"type": "boolean"
},
"auto_close_hours": {
"type": [
"string",
"null"
]
},
"available_groups": {
"items": {},
"type": "array"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"color": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"default_list_filter": {
"type": "string"
},
"default_slow_mode_seconds": {
"type": [
"string",
"null"
]
},
"default_top_period": {
"type": "string"
},
"default_view": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"description_excerpt": {
"type": [
"string",
"null"
]
},
"description_text": {
"type": [
"string",
"null"
]
},
"email_in": {
"type": [
"string",
"null"
]
},
"email_in_allow_strangers": {
"type": "boolean"
},
"form_template_ids": {
"items": {},
"type": "array"
},
"group_permissions": {
"items": {
"additionalProperties": false,
"properties": {
"group_name": {
"type": "string"
},
"permission_type": {
"type": "integer"
}
},
"required": [
"permission_type",
"group_name"
],
"type": "object"
},
"type": "array"
},
"has_children": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"mailinglist_mirror": {
"type": "boolean"
},
"minimum_required_tags": {
"type": "integer"
},
"name": {
"type": "string"
},
"navigate_to_first_post_after_read": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"num_featured_topics": {
"type": "integer"
},
"permission": {
"type": [
"integer",
"null"
]
},
"position": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"read_only_banner": {
"type": [
"string",
"null"
]
},
"read_restricted": {
"type": "boolean"
},
"required_tag_groups": {
"items": {
"additionalProperties": false,
"properties": {
"min_count": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"min_count"
],
"type": "object"
},
"type": "array"
},
"search_priority": {
"type": "integer"
},
"show_subcategory_list": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"sort_ascending": {
"type": [
"string",
"null"
]
},
"sort_order": {
"type": [
"string",
"null"
]
},
"subcategory_list_style": {
"type": "string"
},
"text_color": {
"type": "string"
},
"topic_count": {
"type": "integer"
},
"topic_featured_link_allowed": {
"type": "boolean"
},
"topic_template": {
"type": [
"string",
"null"
]
},
"topic_url": {
"type": [
"string",
"null"
]
},
"uploaded_background": {
"type": [
"string",
"null"
]
},
"uploaded_logo": {
"type": [
"string",
"null"
]
},
"uploaded_logo_dark": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"text_color",
"slug",
"topic_count",
"post_count",
"position",
"description",
"description_text",
"description_excerpt",
"topic_url",
"read_restricted",
"permission",
"notification_level",
"can_edit",
"topic_template",
"has_children",
"sort_order",
"sort_ascending",
"show_subcategory_list",
"num_featured_topics",
"default_view",
"subcategory_list_style",
"default_top_period",
"default_list_filter",
"minimum_required_tags",
"navigate_to_first_post_after_read",
"custom_fields",
"required_tag_groups",
"read_only_banner",
"available_groups",
"auto_close_hours",
"auto_close_based_on_last_post",
"allow_unlimited_owner_edits_on_first_post",
"default_slow_mode_seconds",
"group_permissions",
"email_in",
"email_in_allow_strangers",
"mailinglist_mirror",
"all_topics_wiki",
"can_delete",
"allow_badges",
"topic_featured_link_allowed",
"search_priority",
"uploaded_logo",
"uploaded_logo_dark",
"uploaded_background"
],
"type": "object"
}
},
"required": [
"category"
]
}
}
},
"description": "success response"
}
},
"summary": "Creates a category",
"tags": [
"Categories"
]
}
},
"/categories/{id}.json": {
"put": {
"operationId": "updateCategory",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"allow_badges": {
"type": "boolean"
},
"color": {
"examples": [
"49d9e9"
],
"type": "string"
},
"form_template_ids": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"parent_category_id": {
"type": "integer"
},
"permissions": {
"additionalProperties": true,
"properties": {
"everyone": {
"examples": [
1
],
"type": "integer"
},
"staff": {
"type": "integer"
}
},
"type": "object"
},
"search_priority": {
"type": "integer"
},
"slug": {
"type": "string"
},
"text_color": {
"examples": [
"f0fcfd"
],
"type": "string"
},
"topic_featured_links_allowed": {
"type": "boolean"
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"category": {
"additionalProperties": false,
"properties": {
"all_topics_wiki": {
"type": "boolean"
},
"allow_badges": {
"type": "boolean"
},
"allow_global_tags": {
"type": "boolean"
},
"allow_unlimited_owner_edits_on_first_post": {
"type": "boolean"
},
"allowed_tag_groups": {
"items": {},
"type": "array"
},
"allowed_tags": {
"items": {},
"type": "array"
},
"auto_close_based_on_last_post": {
"type": "boolean"
},
"auto_close_hours": {
"type": [
"string",
"null"
]
},
"available_groups": {
"items": {},
"type": "array"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"color": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"default_list_filter": {
"type": "string"
},
"default_slow_mode_seconds": {
"type": [
"string",
"null"
]
},
"default_top_period": {
"type": "string"
},
"default_view": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"description_excerpt": {
"type": [
"string",
"null"
]
},
"description_text": {
"type": [
"string",
"null"
]
},
"email_in": {
"type": [
"string",
"null"
]
},
"email_in_allow_strangers": {
"type": "boolean"
},
"form_template_ids": {
"items": {},
"type": "array"
},
"group_permissions": {
"items": {
"additionalProperties": false,
"properties": {
"group_name": {
"type": "string"
},
"permission_type": {
"type": "integer"
}
},
"required": [
"permission_type",
"group_name"
],
"type": "object"
},
"type": "array"
},
"has_children": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"mailinglist_mirror": {
"type": "boolean"
},
"minimum_required_tags": {
"type": "integer"
},
"name": {
"type": "string"
},
"navigate_to_first_post_after_read": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"num_featured_topics": {
"type": "integer"
},
"permission": {
"type": [
"string",
"null"
]
},
"position": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"read_only_banner": {
"type": [
"string",
"null"
]
},
"read_restricted": {
"type": "boolean"
},
"required_tag_groups": {
"items": {
"additionalProperties": false,
"properties": {
"min_count": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"min_count"
],
"type": "object"
},
"type": "array"
},
"search_priority": {
"type": "integer"
},
"show_subcategory_list": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"sort_ascending": {
"type": [
"string",
"null"
]
},
"sort_order": {
"type": [
"string",
"null"
]
},
"subcategory_list_style": {
"type": "string"
},
"text_color": {
"type": "string"
},
"topic_count": {
"type": "integer"
},
"topic_featured_link_allowed": {
"type": "boolean"
},
"topic_template": {
"type": [
"string",
"null"
]
},
"topic_url": {
"type": [
"string",
"null"
]
},
"uploaded_background": {
"type": [
"string",
"null"
]
},
"uploaded_logo": {
"type": [
"string",
"null"
]
},
"uploaded_logo_dark": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"text_color",
"slug",
"topic_count",
"post_count",
"position",
"description",
"description_text",
"description_excerpt",
"topic_url",
"read_restricted",
"permission",
"notification_level",
"can_edit",
"topic_template",
"form_template_ids",
"has_children",
"sort_order",
"sort_ascending",
"show_subcategory_list",
"num_featured_topics",
"default_view",
"subcategory_list_style",
"default_top_period",
"default_list_filter",
"minimum_required_tags",
"navigate_to_first_post_after_read",
"custom_fields",
"required_tag_groups",
"read_only_banner",
"available_groups",
"auto_close_hours",
"auto_close_based_on_last_post",
"allow_unlimited_owner_edits_on_first_post",
"default_slow_mode_seconds",
"group_permissions",
"email_in",
"email_in_allow_strangers",
"mailinglist_mirror",
"all_topics_wiki",
"can_delete",
"allow_badges",
"topic_featured_link_allowed",
"search_priority",
"uploaded_logo",
"uploaded_logo_dark",
"uploaded_background"
],
"type": "object"
},
"success": {
"type": "string"
}
},
"required": [
"success",
"category"
]
}
}
},
"description": "success response"
}
},
"summary": "Updates a category",
"tags": [
"Categories"
]
}
},
"/directory_items.json": {
"get": {
"operationId": "listUsersPublic",
"parameters": [
{
"in": "query",
"name": "period",
"required": true,
"schema": {
"enum": [
"daily",
"weekly",
"monthly",
"quarterly",
"yearly",
"all"
],
"type": "string"
}
},
{
"in": "query",
"name": "order",
"required": true,
"schema": {
"enum": [
"likes_received",
"likes_given",
"topic_count",
"post_count",
"topics_entered",
"posts_read",
"days_visited"
],
"type": "string"
}
},
{
"in": "query",
"name": "asc",
"schema": {
"enum": [
"true"
],
"type": "string"
}
},
{
"in": "query",
"name": "page",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"directory_items": {
"items": {
"additionalProperties": false,
"properties": {
"days_visited": {
"type": "integer"
},
"id": {
"type": "integer"
},
"likes_given": {
"type": "integer"
},
"likes_received": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"posts_read": {
"type": "integer"
},
"topic_count": {
"type": "integer"
},
"topics_entered": {
"type": "integer"
},
"user": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"title"
],
"type": "object"
}
},
"required": [
"id",
"likes_received",
"likes_given",
"topics_entered",
"topic_count",
"post_count",
"posts_read",
"days_visited",
"user"
],
"type": "object"
},
"type": "array"
},
"meta": {
"additionalProperties": false,
"properties": {
"last_updated_at": {
"type": [
"string",
"null"
]
},
"load_more_directory_items": {
"type": "string"
},
"total_rows_directory_items": {
"type": "integer"
}
},
"required": [
"last_updated_at",
"total_rows_directory_items",
"load_more_directory_items"
],
"type": "object"
}
},
"required": [
"directory_items",
"meta"
]
}
}
},
"description": "directory items response"
}
},
"summary": "Get a public list of users",
"tags": [
"Users"
]
}
},
"/groups.json": {
"get": {
"operationId": "listGroups",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"extras": {
"additionalProperties": false,
"properties": {
"type_filters": {
"items": {},
"type": "array"
}
},
"required": [
"type_filters"
],
"type": "object"
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_edit_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"is_group_owner": {
"type": "boolean"
},
"is_group_user": {
"type": "boolean"
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"load_more_groups": {
"type": "string"
},
"total_rows_groups": {
"type": "integer"
}
},
"required": [
"groups",
"extras",
"total_rows_groups",
"load_more_groups"
]
}
}
},
"description": "response"
}
},
"summary": "List groups",
"tags": [
"Groups"
]
}
},
"/groups/{id}.json": {
"get": {
"operationId": "getGroup",
"parameters": [
{
"description": "Use group name instead of id",
"example": "name",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"extras": {
"additionalProperties": false,
"properties": {
"visible_group_names": {
"items": {},
"type": "array"
}
},
"required": [
"visible_group_names"
],
"type": "object"
},
"group": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"allow_unknown_sender_topic_replies": {
"type": "boolean"
},
"associated_group_ids": {
"items": {},
"type": "array"
},
"automatic": {
"type": "boolean"
},
"automatic_membership_email_domains": {
"type": [
"string",
"null"
]
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_edit_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"email_from_alias": {
"type": [
"string",
"null"
]
},
"email_password": {
"type": [
"string",
"null"
]
},
"email_username": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"imap_enabled": {
"type": "boolean"
},
"imap_last_error": {
"type": [
"string",
"null"
]
},
"imap_mailbox_name": {
"type": "string"
},
"imap_mailboxes": {
"items": {},
"type": "array"
},
"imap_new_emails": {
"type": [
"string",
"null"
]
},
"imap_old_emails": {
"type": [
"string",
"null"
]
},
"imap_port": {
"type": [
"string",
"null"
]
},
"imap_server": {
"type": [
"string",
"null"
]
},
"imap_ssl": {
"type": [
"string",
"null"
]
},
"imap_updated_at": {
"type": [
"string",
"null"
]
},
"imap_updated_by": {
"type": [
"object",
"null"
]
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"is_group_owner_display": {
"type": "boolean"
},
"is_group_user": {
"type": "boolean"
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable": {
"type": "boolean"
},
"mentionable_level": {
"type": "integer"
},
"message_count": {
"type": "integer"
},
"messageable": {
"type": "boolean"
},
"messageable_level": {
"type": "integer"
},
"muted_category_ids": {
"items": {},
"type": "array"
},
"muted_tags": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"regular_category_ids": {
"items": {},
"type": "array"
},
"regular_tags": {
"items": {},
"type": "array"
},
"smtp_enabled": {
"type": "boolean"
},
"smtp_port": {
"type": [
"string",
"null"
]
},
"smtp_server": {
"type": [
"string",
"null"
]
},
"smtp_ssl": {
"type": [
"string",
"null"
]
},
"smtp_updated_at": {
"type": [
"string",
"null"
]
},
"smtp_updated_by": {
"type": [
"object",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"tracking_category_ids": {
"items": {},
"type": "array"
},
"tracking_tags": {
"items": {},
"type": "array"
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
},
"watching_category_ids": {
"items": {},
"type": "array"
},
"watching_first_post_category_ids": {
"items": {},
"type": "array"
},
"watching_first_post_tags": {
"items": {},
"type": "array"
},
"watching_tags": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"automatic",
"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",
"is_group_user",
"members_visibility_level",
"can_see_members",
"can_admin_group",
"publish_read_state",
"is_group_owner_display",
"mentionable",
"messageable",
"automatic_membership_email_domains",
"smtp_server",
"smtp_port",
"smtp_ssl",
"imap_server",
"imap_port",
"imap_ssl",
"imap_mailbox_name",
"imap_mailboxes",
"email_username",
"email_password",
"imap_last_error",
"imap_old_emails",
"imap_new_emails",
"message_count",
"allow_unknown_sender_topic_replies",
"watching_category_ids",
"tracking_category_ids",
"watching_first_post_category_ids",
"regular_category_ids",
"muted_category_ids"
],
"type": "object"
}
},
"required": [
"group",
"extras"
]
}
}
},
"description": "success response"
}
},
"summary": "Get a group",
"tags": [
"Groups"
]
},
"put": {
"operationId": "updateGroup",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"group": {
"additionalProperties": false,
"properties": {
"automatic_membership_email_domains": {
"description": "pipe|separated",
"type": "string"
},
"bio_raw": {
"description": "About Group",
"type": "string"
},
"default_notification_level": {
"type": "integer"
},
"flair_bg_color": {
"type": "string"
},
"flair_icon": {
"type": "string"
},
"flair_upload_id": {
"type": "integer"
},
"full_name": {
"type": "string"
},
"muted_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"name": {
"type": "string"
},
"owner_usernames": {
"description": "comma,separated",
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"regular_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"tracking_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"usernames": {
"description": "comma,separated",
"type": "string"
},
"visibility_level": {
"type": "integer"
},
"watching_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
},
"watching_first_post_category_ids": {
"items": {
"type": "integer"
},
"type": "array"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"group"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"type": "object"
}
}
},
"description": "success response"
}
},
"summary": "Update a group",
"tags": [
"Groups"
]
}
},
"/groups/{id}/members.json": {
"delete": {
"operationId": "removeGroupMembers",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"usernames": {
"description": "comma separated list",
"examples": [
"username1,username2"
],
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"skipped_usernames": {
"items": {},
"type": "array"
},
"success": {
"type": "string"
},
"usernames": {
"items": {},
"type": "array"
}
},
"required": [
"success",
"usernames",
"skipped_usernames"
]
}
}
},
"description": "success response"
}
},
"summary": "Remove group members",
"tags": [
"Groups"
]
},
"get": {
"operationId": "listGroupMembers",
"parameters": [
{
"description": "Use group name instead of id",
"example": "name",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"members": {
"items": {
"additionalProperties": false,
"properties": {
"added_at": {
"type": "string"
},
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"last_posted_at": {
"type": "string"
},
"last_seen_at": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"title",
"last_posted_at",
"last_seen_at",
"added_at",
"timezone"
],
"type": "object"
},
"type": "array"
},
"meta": {
"additionalProperties": false,
"properties": {
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"total": {
"type": "integer"
}
},
"required": [
"total",
"limit",
"offset"
],
"type": "object"
},
"owners": {
"items": {
"additionalProperties": false,
"properties": {
"added_at": {
"type": "string"
},
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"last_posted_at": {
"type": "string"
},
"last_seen_at": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"title",
"last_posted_at",
"last_seen_at",
"added_at",
"timezone"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"members",
"owners",
"meta"
]
}
}
},
"description": "success response"
}
},
"summary": "List group members",
"tags": [
"Groups"
]
},
"put": {
"operationId": "addGroupMembers",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"usernames": {
"description": "comma separated list",
"examples": [
"username1,username2"
],
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"emails": {
"items": {},
"type": "array"
},
"success": {
"type": "string"
},
"usernames": {
"items": {},
"type": "array"
}
},
"required": [
"success",
"usernames",
"emails"
]
}
}
},
"description": "success response"
}
},
"summary": "Add group members",
"tags": [
"Groups"
]
}
},
"/invites.json": {
"post": {
"operationId": "createInvite",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"custom_message": {
"description": "optional, for email invites",
"type": "string"
},
"email": {
"description": "required for email invites only",
"examples": [
"not-a-user-yet@example.com"
],
"type": "string"
},
"expires_at": {
"description": "optional, if not supplied, the invite_expiry_days site\nsetting is used",
"type": "string"
},
"group_id": {
"description": "optional, either this or `group_names`",
"type": "integer"
},
"group_names": {
"description": "optional, either this or `group_id`",
"type": "string"
},
"max_redemptions_allowed": {
"default": 1,
"description": "optional, for link invites",
"examples": [
5
],
"type": "integer"
},
"skip_email": {
"default": false,
"type": "boolean"
},
"topic_id": {
"type": "integer"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"created_at": {
"examples": [
"2021-01-01T12:00:00.000Z"
],
"type": "string"
},
"custom_message": {
"examples": [
"Hello world!"
],
"type": [
"string",
"null"
]
},
"email": {
"examples": [
"not-a-user-yet@example.com"
],
"type": "string"
},
"emailed": {
"examples": [
false
],
"type": "boolean"
},
"expired": {
"examples": [
false
],
"type": "boolean"
},
"expires_at": {
"examples": [
"2021-02-01T12:00:00.000Z"
],
"type": "string"
},
"groups": {
"examples": [
[]
],
"items": {},
"type": "array"
},
"id": {
"examples": [
42
],
"type": "integer"
},
"link": {
"examples": [
"http://example.com/invites/9045fd767efe201ca60c6658bcf14158"
],
"type": "string"
},
"topics": {
"examples": [
[]
],
"items": {},
"type": "array"
},
"updated_at": {
"examples": [
"2021-01-01T12:00:00.000Z"
],
"type": "string"
}
},
"type": "object"
}
}
},
"description": "success response"
}
},
"summary": "Create an invite",
"tags": [
"Invites"
]
}
},
"/latest.json": {
"get": {
"operationId": "listLatestTopics",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Enum: `default`, `created`, `activity`, `views`, `posts`, `category`,\n`likes`, `op_likes`, `posters`",
"in": "query",
"name": "order",
"schema": {
"type": "string"
}
},
{
"description": "Defaults to `desc`, add `ascending=true` to sort asc",
"in": "query",
"name": "ascending",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"properties": {
"can_create_topic": {
"type": "boolean"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"topics": {
"items": {
"properties": {
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": "string"
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"last_read_post_number": {
"type": "integer"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"op_like_count": {
"type": "integer"
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unread_posts": {
"type": "integer"
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"users": {
"items": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Get the latest topics",
"tags": [
"Topics"
]
}
},
"/notifications.json": {
"get": {
"operationId": "getNotifications",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"load_more_notifications": {
"type": "string"
},
"notifications": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"data": {
"properties": {
"badge_id": {
"type": "integer"
},
"badge_name": {
"type": "string"
},
"badge_slug": {
"type": "string"
},
"badge_title": {
"type": "boolean"
},
"username": {
"type": "string"
}
},
"type": "object"
},
"id": {
"type": "integer"
},
"notification_type": {
"type": "integer"
},
"post_number": {
"type": [
"string",
"null"
]
},
"read": {
"type": "boolean"
},
"slug": {
"type": [
"string",
"null"
]
},
"topic_id": {
"type": [
"integer",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"seen_notification_id": {
"type": "integer"
},
"total_rows_notifications": {
"type": "integer"
}
},
"type": "object"
}
}
},
"description": "notifications"
}
},
"summary": "Get the notifications that belong to the current user",
"tags": [
"Notifications"
]
}
},
"/notifications/mark-read.json": {
"put": {
"operationId": "markNotificationsAsRead",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"description": "(optional) Leave off to mark all notifications as\nread",
"type": "integer"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "notifications marked read"
}
},
"summary": "Mark notifications as read",
"tags": [
"Notifications"
]
}
},
"/post_actions.json": {
"post": {
"operationId": "performPostAction",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"flag_topic": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"post_action_type_id": {
"type": "integer"
}
},
"required": [
"id",
"post_action_type_id"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"actions_summary": {
"items": {
"properties": {
"acted": {
"type": "boolean"
},
"can_undo": {
"type": "boolean"
},
"count": {
"type": "integer"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": "string"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"notice": {
"type": "object"
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "number"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"type": "object"
}
}
},
"description": "post updated"
}
},
"summary": "Like a post and other actions",
"tags": [
"Posts"
]
}
},
"/posts.json": {
"get": {
"operationId": "listPosts",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Load posts with an id lower than this value. Useful for pagination.",
"in": "query",
"name": "before",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"latest_posts": {
"items": {
"properties": {
"actions_summary": {
"items": {
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"category_id": {
"type": "integer"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": "string"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"raw": {
"type": "string"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "number"
},
"staff": {
"type": "boolean"
},
"topic_html_title": {
"type": "string"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"topic_title": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "latest posts"
}
},
"summary": "List latest posts across topics",
"tags": [
"Posts"
]
},
"post": {
"operationId": "createTopicPostPM",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"archetype": {
"description": "Required for new private message.",
"examples": [
"private_message"
],
"type": "string"
},
"category": {
"description": "Optional if creating a new topic, and ignored if creating\na new post.",
"type": "integer"
},
"created_at": {
"type": "string"
},
"embed_url": {
"description": "Provide a URL from a remote system to associate a forum\ntopic with that URL, typically for using Discourse as a comments\nsystem for an external blog.",
"type": "string"
},
"external_id": {
"description": "Provide an external_id from a remote system to associate\na forum topic with that id.",
"type": "string"
},
"raw": {
"type": "string"
},
"target_recipients": {
"description": "Required for private message, comma separated.",
"examples": [
"blake,sam"
],
"type": "string"
},
"target_usernames": {
"deprecated": true,
"description": "Deprecated. Use target_recipients instead.",
"type": "string"
},
"title": {
"description": "Required if creating a new topic or new private message.",
"type": "string"
},
"topic_id": {
"description": "Required if creating a new post.",
"type": "integer"
}
},
"required": [
"raw"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"actions_summary": {
"items": {
"additionalProperties": false,
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"required": [
"id",
"can_act"
],
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"bookmarked": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
},
"draft_sequence": {
"type": "integer"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"mentioned_users": {
"items": {},
"type": "array"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"raw": {
"type": "string"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "integer"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"username",
"avatar_template",
"created_at",
"cooked",
"post_number",
"post_type",
"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"
]
}
}
},
"description": "post created"
}
},
"summary": "Creates a new topic, a new post, or a private message",
"tags": [
"Posts",
"Topics",
"Private Messages"
]
}
},
"/posts/{id}.json": {
"delete": {
"operationId": "deletePost",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"force_destroy": {
"description": "The `SiteSetting.can_permanently_delete` needs to be\nenabled first before this param can be used. Also this endpoint\nneeds to be called first without `force_destroy` and then followed\nup with a second call 5 minutes later with `force_destroy` to\npermanently delete.",
"examples": [
true
],
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "success response"
}
},
"summary": "delete a single post",
"tags": [
"Posts"
]
},
"get": {
"operationId": "getPost",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"actions_summary": {
"items": {
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"raw": {
"type": "string"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "integer"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"type": "object"
}
}
},
"description": "latest posts"
}
},
"summary": "Retrieve a single post",
"tags": [
"Posts"
]
},
"put": {
"operationId": "updatePost",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"post": {
"properties": {
"edit_reason": {
"type": "string"
},
"raw": {
"type": "string"
}
},
"required": [
"raw"
],
"type": "object"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"post": {
"properties": {
"actions_summary": {
"items": {
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
},
"draft_sequence": {
"type": "integer"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "number"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "post updated"
}
},
"summary": "Update a single post",
"tags": [
"Posts"
]
}
},
"/posts/{id}/locked.json": {
"put": {
"operationId": "lockPost",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"locked": {
"type": "string"
}
},
"required": [
"locked"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"locked": {
"type": "boolean"
}
},
"type": "object"
}
}
},
"description": "post updated"
}
},
"summary": "Lock a post from being edited",
"tags": [
"Posts"
]
}
},
"/posts/{id}/replies.json": {
"get": {
"operationId": "postReplies",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"actions_summary": {
"items": {
"additionalProperties": false,
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"required": [
"id",
"can_act"
],
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"bookmarked": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": "integer"
},
"reply_to_user": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"username",
"avatar_template"
],
"type": "object"
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "integer"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"username",
"avatar_template",
"created_at",
"cooked",
"post_number",
"post_type",
"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",
"reply_to_user",
"bookmarked",
"actions_summary",
"moderator",
"admin",
"staff",
"user_id",
"hidden",
"trust_level",
"deleted_at",
"user_deleted",
"edit_reason",
"can_view_edit_history",
"wiki",
"reviewable_id",
"reviewable_score_count",
"reviewable_score_pending_count"
],
"type": "object"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
}
},
"description": "post replies"
}
},
"summary": "List replies to a post",
"tags": [
"Posts"
]
}
},
"/search.json": {
"get": {
"operationId": "search",
"parameters": [
{
"description": "The query string needs to be url encoded and is made up of the following options:\n- Search term. This is just a string. Usually it would be the first item in the query.\n- `@<username>`: Use the `@` followed by the username to specify posts by this user.\n- `#<category>`: Use the `#` followed by the category slug to search within this category.\n- `tags:`: `api,solved` or for posts that have all the specified tags `api+solved`.\n- `before:`: `yyyy-mm-dd`\n- `after:`: `yyyy-mm-dd`\n- `order:`: `latest`, `likes`, `views`, `latest_topic`\n- `assigned:`: username (without `@`)\n- `in:`: `title`, `likes`, `personal`, `messages`, `seen`, `unseen`, `posted`, `created`, `watching`, `tracking`, `bookmarks`, `assigned`, `unassigned`, `first`, `pinned`, `wiki`\n- `with:`: `images`\n- `status:`: `open`, `closed`, `public`, `archived`, `noreplies`, `single_user`, `solved`, `unsolved`\n- `group:`: group_name or group_id\n- `group_messages:`: group_name or group_id\n- `min_posts:`: 1\n- `max_posts:`: 10\n- `min_views:`: 1\n- `max_views:`: 10\n\nIf you are using cURL you can use the `-G` and the `--data-urlencode` flags to encode the query:\n\n```\ncurl -i -sS -X GET -G \"http://localhost:4200/search.json\" \\\n--data-urlencode 'q=wordpress @scossar #fun after:2020-01-01'\n```\n",
"example": "api @blake #support tags:api after:2021-06-04 in:unseen in:open\norder:latest_topic",
"in": "query",
"name": "q",
"schema": {
"type": "string"
}
},
{
"example": 1,
"in": "query",
"name": "page",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"categories": {
"items": {},
"type": "array"
},
"grouped_search_result": {
"additionalProperties": false,
"properties": {
"can_create_topic": {
"type": "boolean"
},
"category_ids": {
"items": {},
"type": "array"
},
"error": {
"type": [
"string",
"null"
]
},
"group_ids": {
"items": {},
"type": "array"
},
"more_categories": {
"type": [
"string",
"null"
]
},
"more_full_page_results": {
"type": [
"string",
"null"
]
},
"more_posts": {
"type": [
"string",
"null"
]
},
"more_users": {
"type": [
"string",
"null"
]
},
"post_ids": {
"items": {},
"type": "array"
},
"search_log_id": {
"type": "integer"
},
"tag_ids": {
"items": {},
"type": "array"
},
"term": {
"type": "string"
},
"user_ids": {
"items": {},
"type": "array"
}
},
"required": [
"more_posts",
"more_users",
"more_categories",
"term",
"search_log_id",
"more_full_page_results",
"can_create_topic",
"error",
"post_ids",
"user_ids",
"category_ids",
"tag_ids",
"group_ids"
],
"type": "object"
},
"groups": {
"items": {},
"type": "array"
},
"posts": {
"items": {},
"type": "array"
},
"tags": {
"items": {},
"type": "array"
},
"users": {
"items": {},
"type": "array"
}
},
"required": [
"posts",
"users",
"categories",
"tags",
"groups",
"grouped_search_result"
]
}
}
},
"description": "success response"
}
},
"summary": "Search for a term",
"tags": [
"Search"
]
}
},
"/session/forgot_password.json": {
"post": {
"operationId": "sendPasswordResetEmail",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"login": {
"type": "string"
}
},
"required": [
"login"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"type": "string"
},
"user_found": {
"type": "boolean"
}
},
"required": [
"success",
"user_found"
]
}
}
},
"description": "success response"
}
},
"summary": "Send password reset email",
"tags": [
"Users"
]
}
},
"/site.json": {
"get": {
"description": "Can be used to fetch all categories and subcategories",
"operationId": "getSite",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"anonymous_top_menu_items": {
"items": {},
"type": "array"
},
"archetypes": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"options": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"name",
"options"
],
"type": "object"
},
"type": "array"
},
"auth_providers": {
"items": {},
"type": "array"
},
"can_associate_groups": {
"type": "boolean"
},
"can_create_tag": {
"type": "boolean"
},
"can_tag_pms": {
"type": "boolean"
},
"can_tag_topics": {
"type": "boolean"
},
"categories": {
"items": {
"additionalProperties": false,
"properties": {
"allow_global_tags": {
"type": "boolean"
},
"allowed_tag_groups": {
"items": {},
"type": "array"
},
"allowed_tags": {
"items": {},
"type": "array"
},
"can_edit": {
"type": "boolean"
},
"color": {
"type": "string"
},
"custom_fields": {
"additionalProperties": true,
"type": [
"object",
"null"
]
},
"default_list_filter": {
"type": "string"
},
"default_top_period": {
"type": "string"
},
"default_view": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"description_excerpt": {
"type": [
"string",
"null"
]
},
"description_text": {
"type": [
"string",
"null"
]
},
"form_template_ids": {
"items": {},
"type": "array"
},
"has_children": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"minimum_required_tags": {
"type": "integer"
},
"name": {
"type": "string"
},
"navigate_to_first_post_after_read": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"num_featured_topics": {
"type": "integer"
},
"parent_category_id": {
"type": "integer"
},
"permission": {
"type": "integer"
},
"position": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"read_only_banner": {
"type": [
"string",
"null"
]
},
"read_restricted": {
"type": "boolean"
},
"required_tag_groups": {
"items": {
"additionalProperties": false,
"properties": {
"min_count": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"min_count"
],
"type": "object"
},
"type": "array"
},
"show_subcategory_list": {
"type": "boolean"
},
"slug": {
"type": "string"
},
"sort_ascending": {
"type": [
"string",
"null"
]
},
"sort_order": {
"type": [
"string",
"null"
]
},
"subcategory_list_style": {
"type": "string"
},
"text_color": {
"type": "string"
},
"topic_count": {
"type": "integer"
},
"topic_template": {
"type": [
"string",
"null"
]
},
"topic_url": {
"type": "string"
},
"uploaded_background": {
"type": [
"string",
"null"
]
},
"uploaded_logo": {
"type": [
"string",
"null"
]
},
"uploaded_logo_dark": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"text_color",
"slug",
"topic_count",
"post_count",
"position",
"topic_url",
"read_restricted",
"permission",
"notification_level",
"topic_template",
"has_children",
"sort_order",
"sort_ascending",
"show_subcategory_list",
"num_featured_topics",
"default_view",
"subcategory_list_style",
"default_top_period",
"default_list_filter",
"minimum_required_tags",
"navigate_to_first_post_after_read",
"allowed_tags",
"allowed_tag_groups",
"allow_global_tags",
"required_tag_groups",
"read_only_banner",
"uploaded_logo",
"uploaded_logo_dark",
"uploaded_background",
"can_edit"
],
"type": "object"
},
"type": "array"
},
"censored_regexp": {
"items": {
"type": "object"
},
"type": "array"
},
"custom_emoji_translation": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"default_archetype": {
"type": "string"
},
"default_dark_color_scheme": {
"type": [
"object",
"null"
]
},
"displayed_about_plugin_stat_groups": {
"type": "array"
},
"filters": {
"items": {},
"type": "array"
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"flair_url",
"flair_bg_color",
"flair_color"
],
"type": "object"
},
"type": "array"
},
"hashtag_configurations": {
"type": "object"
},
"hashtag_icons": {
"type": "array"
},
"markdown_additional_options": {
"type": "object"
},
"notification_types": {
"additionalProperties": false,
"properties": {
"assigned": {
"type": "integer"
},
"bookmark_reminder": {
"type": "integer"
},
"chat_group_mention": {
"type": "integer"
},
"chat_invitation": {
"type": "integer"
},
"chat_mention": {
"type": "integer"
},
"chat_message": {
"type": "integer"
},
"chat_quoted": {
"type": "integer"
},
"circles_activity": {
"type": "integer"
},
"code_review_commit_approved": {
"type": "integer"
},
"custom": {
"type": "integer"
},
"edited": {
"type": "integer"
},
"event_invitation": {
"type": "integer"
},
"event_reminder": {
"type": "integer"
},
"following": {
"type": "integer"
},
"following_created_topic": {
"type": "integer"
},
"following_replied": {
"type": "integer"
},
"granted_badge": {
"type": "integer"
},
"group_mentioned": {
"type": "integer"
},
"group_message_summary": {
"type": "integer"
},
"invited_to_private_message": {
"type": "integer"
},
"invited_to_topic": {
"type": "integer"
},
"invitee_accepted": {
"type": "integer"
},
"liked": {
"type": "integer"
},
"liked_consolidated": {
"type": "integer"
},
"linked": {
"type": "integer"
},
"membership_request_accepted": {
"type": "integer"
},
"membership_request_consolidated": {
"type": "integer"
},
"mentioned": {
"type": "integer"
},
"moved_post": {
"type": "integer"
},
"new_features": {
"type": "integer"
},
"post_approved": {
"type": "integer"
},
"posted": {
"type": "integer"
},
"private_message": {
"type": "integer"
},
"question_answer_user_commented": {
"type": "integer"
},
"quoted": {
"type": "integer"
},
"reaction": {
"type": "integer"
},
"replied": {
"type": "integer"
},
"topic_reminder": {
"type": "integer"
},
"votes_released": {
"type": "integer"
},
"watching_category_or_tag": {
"type": "integer"
},
"watching_first_post": {
"type": "integer"
}
},
"required": [
"mentioned",
"replied",
"quoted",
"edited",
"liked",
"private_message",
"invited_to_private_message",
"invitee_accepted",
"posted",
"watching_category_or_tag",
"moved_post",
"linked",
"granted_badge",
"invited_to_topic",
"custom",
"group_mentioned",
"group_message_summary",
"watching_first_post",
"topic_reminder",
"liked_consolidated",
"post_approved",
"code_review_commit_approved",
"membership_request_accepted",
"membership_request_consolidated",
"bookmark_reminder",
"reaction",
"votes_released",
"event_reminder",
"event_invitation",
"chat_mention",
"chat_message",
"chat_invitation",
"chat_group_mention"
],
"type": "object"
},
"periods": {
"items": {},
"type": "array"
},
"post_action_types": {
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"id": {
"type": [
"integer",
"null"
]
},
"is_custom_flag": {
"type": "boolean"
},
"is_flag": {
"type": "boolean"
},
"name": {
"type": "string"
},
"name_key": {
"type": [
"string",
"null"
]
},
"short_description": {
"type": "string"
}
},
"required": [
"id",
"name_key",
"name",
"description",
"short_description",
"is_flag",
"is_custom_flag"
],
"type": "object"
},
"type": "array"
},
"post_types": {
"additionalProperties": false,
"properties": {
"moderator_action": {
"type": "integer"
},
"regular": {
"type": "integer"
},
"small_action": {
"type": "integer"
},
"whisper": {
"type": "integer"
}
},
"required": [
"regular",
"moderator_action",
"small_action",
"whisper"
],
"type": "object"
},
"show_welcome_topic_banner": {
"type": "boolean"
},
"tags_filter_regexp": {
"type": "string"
},
"top_menu_items": {
"items": {},
"type": "array"
},
"top_tags": {
"items": {},
"type": "array"
},
"topic_featured_link_allowed_category_ids": {
"items": {},
"type": "array"
},
"topic_flag_types": {
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"id": {
"type": [
"integer",
"null"
]
},
"is_custom_flag": {
"type": "boolean"
},
"is_flag": {
"type": "boolean"
},
"name": {
"type": "string"
},
"name_key": {
"type": [
"string",
"null"
]
},
"short_description": {
"type": "string"
}
},
"required": [
"id",
"name_key",
"name",
"description",
"short_description",
"is_flag",
"is_custom_flag"
],
"type": "object"
},
"type": "array"
},
"trust_levels": {
"additionalProperties": false,
"properties": {
"basic": {
"type": "integer"
},
"leader": {
"type": "integer"
},
"member": {
"type": "integer"
},
"newuser": {
"type": "integer"
},
"regular": {
"type": "integer"
}
},
"required": [
"newuser",
"basic",
"member",
"regular",
"leader"
],
"type": "object"
},
"uncategorized_category_id": {
"type": "integer"
},
"user_color_schemes": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"is_dark": {
"type": "boolean"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"is_dark"
],
"type": "object"
},
"type": "array"
},
"user_field_max_length": {
"type": "integer"
},
"user_fields": {
"items": {},
"type": "array"
},
"user_themes": {
"items": {
"additionalProperties": false,
"properties": {
"color_scheme_id": {
"type": [
"integer",
"null"
]
},
"default": {
"type": "boolean"
},
"name": {
"type": "string"
},
"theme_id": {
"type": "integer"
}
},
"required": [
"theme_id",
"name",
"default",
"color_scheme_id"
],
"type": "object"
},
"type": "array"
},
"watched_words_link": {
"type": [
"string",
"null"
]
},
"watched_words_replace": {
"type": [
"string",
"null"
]
},
"whispers_allowed_groups_names": {
"type": "array"
},
"wizard_required": {
"type": "boolean"
}
},
"required": [
"default_archetype",
"notification_types",
"post_types",
"trust_levels",
"groups",
"filters",
"periods",
"top_menu_items",
"anonymous_top_menu_items",
"uncategorized_category_id",
"user_field_max_length",
"post_action_types",
"topic_flag_types",
"can_create_tag",
"can_tag_topics",
"can_tag_pms",
"tags_filter_regexp",
"top_tags",
"topic_featured_link_allowed_category_ids",
"user_themes",
"user_color_schemes",
"default_dark_color_scheme",
"censored_regexp",
"custom_emoji_translation",
"watched_words_replace",
"watched_words_link",
"categories",
"archetypes",
"user_fields",
"auth_providers"
]
}
}
},
"description": "success response"
}
},
"summary": "Get site info",
"tags": [
"Site",
"Categories"
]
}
},
"/t/-/{id}.json": {
"put": {
"operationId": "updateTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"topic": {
"properties": {
"category_id": {
"type": "integer"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"basic_topic": {
"properties": {
"fancy_title": {
"type": "string"
},
"id": {
"type": "integer"
},
"posts_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Update a topic",
"tags": [
"Topics"
]
}
},
"/t/external_id/{external_id}.json": {
"get": {
"operationId": "getTopicByExternalId",
"parameters": [
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"301": {
"description": "redirects to /t/{topic_id}.json"
}
},
"summary": "Get topic by external_id",
"tags": [
"Topics"
]
}
},
"/t/{id}.json": {
"delete": {
"operationId": "removeTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "specific posts"
}
},
"summary": "Remove a topic",
"tags": [
"Topics"
]
},
"get": {
"operationId": "getTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"actions_summary": {
"items": {
"additionalProperties": false,
"properties": {
"can_act": {
"type": "boolean"
},
"count": {
"type": "integer"
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"required": [
"id",
"count",
"hidden",
"can_act"
],
"type": "object"
},
"type": "array"
},
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bookmarks": {
"items": {},
"type": "array"
},
"category_id": {
"type": "integer"
},
"chunk_size": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"current_post_number": {
"type": "integer"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"deleted_by": {
"type": [
"string",
"null"
]
},
"details": {
"additionalProperties": false,
"properties": {
"can_archive_topic": {
"type": "boolean"
},
"can_close_topic": {
"type": "boolean"
},
"can_convert_topic": {
"type": "boolean"
},
"can_create_post": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_edit_staff_notes": {
"type": "boolean"
},
"can_flag_topic": {
"type": "boolean"
},
"can_invite_to": {
"type": "boolean"
},
"can_invite_via_email": {
"type": "boolean"
},
"can_moderate_category": {
"type": "boolean"
},
"can_move_posts": {
"type": "boolean"
},
"can_pin_unpin_topic": {
"type": "boolean"
},
"can_remove_allowed_users": {
"type": "boolean"
},
"can_remove_self_id": {
"type": "integer"
},
"can_reply_as_new_topic": {
"type": "boolean"
},
"can_review_topic": {
"type": "boolean"
},
"can_split_merge_topic": {
"type": "boolean"
},
"can_toggle_topic_visibility": {
"type": "boolean"
},
"created_by": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
},
"last_poster": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
},
"notification_level": {
"type": "integer"
},
"participants": {
"items": {
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"post_count": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"trust_level": {
"type": "integer"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"post_count",
"primary_group_name",
"flair_name",
"flair_url",
"flair_color",
"flair_bg_color",
"admin",
"moderator",
"trust_level"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"can_edit",
"notification_level",
"can_move_posts",
"can_delete",
"can_remove_allowed_users",
"can_create_post",
"can_reply_as_new_topic",
"can_convert_topic",
"can_review_topic",
"can_close_topic",
"can_archive_topic",
"can_split_merge_topic",
"can_edit_staff_notes",
"can_toggle_topic_visibility",
"can_pin_unpin_topic",
"can_moderate_category",
"can_remove_self_id",
"created_by",
"last_poster"
],
"type": "object"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_deleted": {
"type": "boolean"
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": [
"integer",
"null"
]
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": [
"string",
"null"
]
},
"like_count": {
"type": "integer"
},
"message_bus_last_id": {
"type": "integer"
},
"participant_count": {
"type": "integer"
},
"pinned": {
"type": "boolean"
},
"pinned_at": {
"type": [
"string",
"null"
]
},
"pinned_globally": {
"type": "boolean"
},
"pinned_until": {
"type": [
"string",
"null"
]
},
"post_stream": {
"additionalProperties": false,
"properties": {
"posts": {
"items": {
"additionalProperties": false,
"properties": {
"actions_summary": {
"items": {
"additionalProperties": false,
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"required": [
"id",
"can_act"
],
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"bookmarked": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": "string"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"link_counts": {
"items": {
"additionalProperties": false,
"properties": {
"clicks": {
"type": "integer"
},
"internal": {
"type": "boolean"
},
"reflection": {
"type": "boolean"
},
"title": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url",
"internal",
"reflection",
"title",
"clicks"
],
"type": "object"
},
"type": "array"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"read": {
"type": "boolean"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": "integer"
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "integer"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"username",
"avatar_template",
"created_at",
"cooked",
"post_number",
"post_type",
"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",
"link_counts",
"read",
"user_title",
"bookmarked",
"actions_summary",
"moderator",
"admin",
"staff",
"user_id",
"hidden",
"trust_level",
"deleted_at",
"user_deleted",
"edit_reason",
"can_view_edit_history",
"wiki",
"reviewable_id",
"reviewable_score_count",
"reviewable_score_pending_count"
],
"type": "object"
},
"type": "array"
},
"stream": {
"items": {},
"type": "array"
}
},
"required": [
"posts",
"stream"
],
"type": "object"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"show_read_indicator": {
"type": "boolean"
},
"slow_mode_enabled_until": {
"type": [
"string",
"null"
]
},
"slow_mode_seconds": {
"type": "integer"
},
"slug": {
"type": "string"
},
"suggested_topics": {
"items": {
"additionalProperties": false,
"properties": {
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": [
"string",
"null"
]
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"excerpt": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": [
"string",
"null"
]
},
"like_count": {
"type": "integer"
},
"liked": {
"type": [
"string",
"null"
]
},
"pinned": {
"type": "boolean"
},
"posters": {
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"user": {
"additionalProperties": false,
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template"
],
"type": "object"
}
},
"required": [
"extras",
"description",
"user"
],
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"tags": {
"items": {},
"type": "array"
},
"tags_descriptions": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"required": [
"id",
"title",
"fancy_title",
"slug",
"posts_count",
"reply_count",
"highest_post_number",
"image_url",
"created_at",
"last_posted_at",
"bumped",
"bumped_at",
"archetype",
"unseen",
"pinned",
"unpinned",
"excerpt",
"visible",
"closed",
"archived",
"bookmarked",
"liked",
"tags",
"tags_descriptions",
"like_count",
"views",
"category_id",
"featured_link",
"posters"
],
"type": "object"
},
"type": "array"
},
"tags": {
"items": {},
"type": "array"
},
"tags_descriptions": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"thumbnails": {
"type": [
"string",
"null"
]
},
"timeline_lookup": {
"items": {},
"type": "array"
},
"title": {
"type": "string"
},
"topic_timer": {
"type": [
"string",
"null"
]
},
"unpinned": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
},
"word_count": {
"type": [
"integer",
"null"
]
}
},
"required": [
"post_stream",
"timeline_lookup",
"suggested_topics",
"tags",
"tags_descriptions",
"id",
"title",
"fancy_title",
"posts_count",
"created_at",
"views",
"reply_count",
"like_count",
"last_posted_at",
"visible",
"closed",
"archived",
"has_summary",
"archetype",
"slug",
"category_id",
"word_count",
"deleted_at",
"user_id",
"featured_link",
"pinned_globally",
"pinned_at",
"pinned_until",
"image_url",
"slow_mode_seconds",
"draft",
"draft_key",
"draft_sequence",
"unpinned",
"pinned",
"highest_post_number",
"deleted_by",
"has_deleted",
"actions_summary",
"chunk_size",
"bookmarked",
"bookmarks",
"topic_timer",
"message_bus_last_id",
"participant_count",
"show_read_indicator",
"thumbnails",
"slow_mode_enabled_until",
"details"
]
}
}
},
"description": "specific posts"
}
},
"summary": "Get a single topic",
"tags": [
"Topics"
]
}
},
"/t/{id}/bookmark.json": {
"put": {
"operationId": "bookmarkTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "topic updated"
}
},
"summary": "Bookmark topic",
"tags": [
"Topics"
]
}
},
"/t/{id}/change-timestamp.json": {
"put": {
"operationId": "updateTopicTimestamp",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"timestamp": {
"examples": [
"1594291380"
],
"type": "string"
}
},
"required": [
"timestamp"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Update topic timestamp",
"tags": [
"Topics"
]
}
},
"/t/{id}/invite.json": {
"post": {
"operationId": "inviteToTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"email": {
"type": "string"
},
"user": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"user": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Invite to topic",
"tags": [
"Topics",
"Invites"
]
}
},
"/t/{id}/notifications.json": {
"post": {
"operationId": "setNotificationLevel",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"notification_level": {
"enum": [
"0",
"1",
"2",
"3"
],
"type": "string"
}
},
"required": [
"notification_level"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Set notification level",
"tags": [
"Topics"
]
}
},
"/t/{id}/posts.json": {
"get": {
"operationId": "getSpecificPostsFromTopic",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"post_ids[]": {
"type": "integer"
}
},
"required": [
"post_ids[]"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "integer"
},
"post_stream": {
"properties": {
"posts": {
"items": {
"properties": {
"actions_summary": {
"items": {
"properties": {
"can_act": {
"type": "boolean"
},
"id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"can_delete": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_view_edit_history": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"cooked": {
"type": "string"
},
"created_at": {
"type": "string"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"read": {
"type": "boolean"
},
"readers_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"reviewable_id": {
"type": "integer"
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"score": {
"type": "integer"
},
"staff": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"user_deleted": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"user_title": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
},
"version": {
"type": "integer"
},
"wiki": {
"type": "boolean"
},
"yours": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "specific posts"
}
},
"summary": "Get specific posts from a topic",
"tags": [
"Topics"
]
}
},
"/t/{id}/status.json": {
"put": {
"operationId": "updateTopicStatus",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"enabled": {
"enum": [
"true",
"false"
],
"type": "string"
},
"status": {
"enum": [
"closed",
"pinned",
"pinned_globally",
"archived",
"visible"
],
"type": "string"
},
"until": {
"description": "Only required for `pinned` and `pinned_globally`",
"examples": [
"2030-12-31"
],
"type": "string"
}
},
"required": [
"status",
"enabled"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
},
"topic_status_update": {
"type": [
"string",
"null"
]
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Update the status of a topic",
"tags": [
"Topics"
]
}
},
"/t/{id}/timer.json": {
"post": {
"operationId": "createTopicTimer",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"based_on_last_post": {
"type": "boolean"
},
"category_id": {
"type": "integer"
},
"status_type": {
"type": "string"
},
"time": {
"examples": [
""
],
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"based_on_last_post": {
"type": "boolean"
},
"category_id": {
"type": [
"string",
"null"
]
},
"closed": {
"type": "boolean"
},
"duration": {
"type": [
"string",
"null"
]
},
"execute_at": {
"type": "string"
},
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"type": "object"
}
}
},
"description": "topic updated"
}
},
"summary": "Create topic timer",
"tags": [
"Topics"
]
}
},
"/tag/{name}.json": {
"get": {
"operationId": "getTag",
"parameters": [
{
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"properties": {
"can_create_topic": {
"type": "boolean"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"tags": {
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"staff": {
"type": "boolean"
},
"topic_count": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"topics": {
"items": {
"properties": {
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"last_read_post_number": {
"type": "integer"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"tags": {
"items": {},
"type": "array"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unread_posts": {
"type": "integer"
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"users": {
"items": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "notifications"
}
},
"summary": "Get a specific tag",
"tags": [
"Tags"
]
}
},
"/tag_groups.json": {
"get": {
"operationId": "listTagGroups",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"tag_groups": {
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"one_per_topic": {
"type": "boolean"
},
"parent_tag_name": {
"items": {},
"type": "array"
},
"permissions": {
"properties": {
"staff": {
"type": "integer"
}
},
"type": "object"
},
"tag_names": {
"items": {},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "tags"
}
},
"summary": "Get a list of tag groups",
"tags": [
"Tags"
]
},
"post": {
"operationId": "createTagGroup",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"tag_group": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"one_per_topic": {
"type": "boolean"
},
"parent_tag_name": {
"items": {},
"type": "array"
},
"permissions": {
"type": "object"
},
"tag_names": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"name",
"tag_names",
"parent_tag_name",
"one_per_topic",
"permissions"
],
"type": "object"
}
},
"required": [
"tag_group"
],
"type": "object"
}
}
},
"description": "tag group created"
}
},
"summary": "Creates a tag group",
"tags": [
"Tags"
]
}
},
"/tag_groups/{id}.json": {
"get": {
"operationId": "getTagGroup",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"tag_group": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"one_per_topic": {
"type": "boolean"
},
"parent_tag_name": {
"items": {},
"type": "array"
},
"permissions": {
"properties": {
"everyone": {
"type": "integer"
}
},
"type": "object"
},
"tag_names": {
"items": {},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "notifications"
}
},
"summary": "Get a single tag group",
"tags": [
"Tags"
]
},
"put": {
"operationId": "updateTagGroup",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"success": {
"type": "string"
},
"tag_group": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"one_per_topic": {
"type": "boolean"
},
"parent_tag_name": {
"items": {},
"type": "array"
},
"permissions": {
"properties": {
"everyone": {
"type": "integer"
}
},
"type": "object"
},
"tag_names": {
"items": {},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": "Tag group updated"
}
},
"summary": "Update tag group",
"tags": [
"Tags"
]
}
},
"/tags.json": {
"get": {
"operationId": "listTags",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"extras": {
"properties": {
"categories": {
"items": {},
"type": "array"
}
},
"type": "object"
},
"tags": {
"items": {
"properties": {
"count": {
"type": "integer"
},
"id": {
"type": "string"
},
"pm_count": {
"type": "integer"
},
"target_tag": {
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "notifications"
}
},
"summary": "Get a list of tags",
"tags": [
"Tags"
]
}
},
"/top.json": {
"get": {
"operationId": "listTopTopics",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Enum: `all`, `yearly`, `quarterly`, `monthly`, `weekly`, `daily`",
"in": "query",
"name": "period",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"properties": {
"can_create_topic": {
"type": "boolean"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"for_period": {
"type": "string"
},
"per_page": {
"type": "integer"
},
"topics": {
"items": {
"properties": {
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"last_read_post_number": {
"type": "integer"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"op_like_count": {
"type": "integer"
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": [
"string",
"null"
]
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"unpinned": {
"type": "boolean"
},
"unread_posts": {
"type": "integer"
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"users": {
"items": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "response"
}
},
"summary": "Get the top topics filtered by period",
"tags": [
"Topics"
]
}
},
"/topics/private-messages-sent/{username}.json": {
"get": {
"operationId": "getUserSentPrivateMessages",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"properties": {
"can_create_topic": {
"type": "boolean"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"topics": {
"items": {
"properties": {
"allowed_user_count": {
"type": "integer"
},
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": [
"string",
"null"
]
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"last_read_post_number": {
"type": "integer"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"participants": {
"items": {},
"type": "array"
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unread_posts": {
"type": "integer"
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"users": {
"items": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"username": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "private messages"
}
},
"summary": "Get a list of private messages sent for a user",
"tags": [
"Private Messages"
]
}
},
"/topics/private-messages/{username}.json": {
"get": {
"operationId": "listUserPrivateMessages",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"primary_groups": {
"items": {},
"type": "array"
},
"topic_list": {
"properties": {
"can_create_topic": {
"type": "boolean"
},
"draft": {
"type": [
"string",
"null"
]
},
"draft_key": {
"type": "string"
},
"draft_sequence": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"topics": {
"items": {
"properties": {
"allowed_user_count": {
"type": "integer"
},
"archetype": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"bookmarked": {
"type": "boolean"
},
"bumped": {
"type": "boolean"
},
"bumped_at": {
"type": "string"
},
"category_id": {
"type": [
"string",
"null"
]
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"fancy_title": {
"type": "string"
},
"featured_link": {
"type": [
"string",
"null"
]
},
"has_summary": {
"type": "boolean"
},
"highest_post_number": {
"type": "integer"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": "string"
},
"last_poster_username": {
"type": "string"
},
"last_read_post_number": {
"type": "integer"
},
"like_count": {
"type": "integer"
},
"liked": {
"type": "boolean"
},
"notification_level": {
"type": "integer"
},
"participants": {
"items": {
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"pinned": {
"type": "boolean"
},
"pinned_globally": {
"type": "boolean"
},
"posters": {
"items": {
"properties": {
"description": {
"type": "string"
},
"extras": {
"type": "string"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"user_id": {
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"posts_count": {
"type": "integer"
},
"reply_count": {
"type": "integer"
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"unpinned": {
"type": [
"string",
"null"
]
},
"unread_posts": {
"type": "integer"
},
"unseen": {
"type": "boolean"
},
"views": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"users": {
"items": {
"properties": {
"avatar_template": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "private messages"
}
},
"summary": "Get a list of private messages for a user",
"tags": [
"Private Messages"
]
}
},
"/u/by-external/{external_id}.json": {
"get": {
"operationId": "getUserExternalId",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"user": {
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean"
},
"allowed_pm_usernames": {
"items": {},
"type": "array"
},
"avatar_template": {
"type": "string"
},
"badge_count": {
"type": "integer"
},
"can_be_deleted": {
"type": "boolean"
},
"can_change_bio": {
"type": "boolean"
},
"can_change_location": {
"type": "boolean"
},
"can_change_tracking_preferences": {
"type": "boolean"
},
"can_change_website": {
"type": "boolean"
},
"can_delete_all_posts": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_edit_email": {
"type": "boolean"
},
"can_edit_name": {
"type": "boolean"
},
"can_edit_username": {
"type": "boolean"
},
"can_ignore_user": {
"type": "boolean"
},
"can_mute_user": {
"type": "boolean"
},
"can_send_private_message_to_user": {
"type": "boolean"
},
"can_send_private_messages": {
"type": "boolean"
},
"can_upload_profile_header": {
"type": "boolean"
},
"can_upload_user_card_background": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {
"first_name": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"featured_topic": {
"type": [
"string",
"null"
]
},
"featured_user_badge_ids": {
"items": {},
"type": "array"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_group_id": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"group_users": {
"items": {
"additionalProperties": false,
"properties": {
"group_id": {
"type": "integer"
},
"notification_level": {
"type": "integer"
},
"owner": {
"type": "boolean"
},
"user_id": {
"type": "integer"
}
},
"required": [
"group_id",
"user_id",
"notification_level"
],
"type": "object"
},
"type": "array"
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"has_title_badges": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"ignored": {
"type": "boolean"
},
"ignored_usernames": {
"items": {},
"type": "array"
},
"invited_by": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"type": [
"string",
"null"
]
},
"locale": {
"type": [
"string",
"null"
]
},
"mailing_list_posts_per_day": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"muted": {
"type": "boolean"
},
"muted_category_ids": {
"items": {},
"type": "array"
},
"muted_tags": {
"items": {},
"type": "array"
},
"muted_usernames": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"pending_count": {
"type": "integer"
},
"pending_posts_count": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"profile_view_count": {
"type": "integer"
},
"recent_time_read": {
"type": "integer"
},
"regular_category_ids": {
"items": {},
"type": "array"
},
"second_factor_backup_enabled": {
"type": "boolean"
},
"second_factor_enabled": {
"type": "boolean"
},
"staged": {
"type": "boolean"
},
"system_avatar_template": {
"type": "string"
},
"system_avatar_upload_id": {
"type": [
"string",
"null"
]
},
"time_read": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"tracked_category_ids": {
"items": {},
"type": "array"
},
"tracked_tags": {
"items": {},
"type": "array"
},
"trust_level": {
"type": "integer"
},
"uploaded_avatar_id": {
"type": [
"string",
"null"
]
},
"use_logo_small_as_avatar": {
"type": "boolean"
},
"user_api_keys": {
"type": [
"string",
"null"
]
},
"user_auth_tokens": {
"items": {
"additionalProperties": false,
"properties": {
"browser": {
"type": "string"
},
"client_ip": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device": {
"type": "string"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_active": {
"type": "boolean"
},
"location": {
"type": "string"
},
"os": {
"type": "string"
},
"seen_at": {
"type": "string"
}
},
"required": [
"id",
"client_ip",
"location",
"browser",
"device",
"os",
"icon",
"created_at",
"seen_at",
"is_active"
],
"type": "object"
},
"type": "array"
},
"user_fields": {
"additionalProperties": false,
"properties": {
"1": {
"type": [
"string",
"null"
]
},
"2": {
"type": [
"string",
"null"
]
}
},
"required": [
"1",
"2"
],
"type": "object"
},
"user_notification_schedule": {
"additionalProperties": false,
"properties": {
"day_0_end_time": {
"type": "integer"
},
"day_0_start_time": {
"type": "integer"
},
"day_1_end_time": {
"type": "integer"
},
"day_1_start_time": {
"type": "integer"
},
"day_2_end_time": {
"type": "integer"
},
"day_2_start_time": {
"type": "integer"
},
"day_3_end_time": {
"type": "integer"
},
"day_3_start_time": {
"type": "integer"
},
"day_4_end_time": {
"type": "integer"
},
"day_4_start_time": {
"type": "integer"
},
"day_5_end_time": {
"type": "integer"
},
"day_5_start_time": {
"type": "integer"
},
"day_6_end_time": {
"type": "integer"
},
"day_6_start_time": {
"type": "integer"
},
"enabled": {
"type": "boolean"
}
},
"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"
],
"type": "object"
},
"user_option": {
"additionalProperties": false,
"properties": {
"allow_private_messages": {
"type": "boolean"
},
"auto_track_topics_after_msecs": {
"type": "integer"
},
"automatically_unpin_topics": {
"type": "boolean"
},
"bookmark_auto_delete_preference": {
"type": "integer"
},
"color_scheme_id": {
"type": [
"string",
"null"
]
},
"dark_scheme_id": {
"type": [
"string",
"null"
]
},
"default_calendar": {
"type": "string"
},
"digest_after_minutes": {
"type": "integer"
},
"dynamic_favicon": {
"type": "boolean"
},
"email_digests": {
"type": "boolean"
},
"email_in_reply_to": {
"type": "boolean"
},
"email_level": {
"type": "integer"
},
"email_messages_level": {
"type": "integer"
},
"email_previous_replies": {
"type": "integer"
},
"enable_allowed_pm_users": {
"type": "boolean"
},
"enable_defer": {
"type": "boolean"
},
"enable_quoting": {
"type": "boolean"
},
"external_links_in_new_tab": {
"type": "boolean"
},
"hide_profile_and_presence": {
"type": "boolean"
},
"homepage_id": {
"type": [
"string",
"null"
]
},
"include_tl0_in_digests": {
"type": "boolean"
},
"like_notification_frequency": {
"type": "integer"
},
"mailing_list_mode": {
"type": "boolean"
},
"mailing_list_mode_frequency": {
"type": "integer"
},
"new_topic_duration_minutes": {
"type": "integer"
},
"notification_level_when_replying": {
"type": "integer"
},
"oldest_search_log_date": {
"type": [
"string",
"null"
]
},
"seen_popups": {
"type": [
"array",
"null"
]
},
"sidebar_list_destination": {
"type": "string"
},
"skip_new_user_tips": {
"type": "boolean"
},
"text_size": {
"type": "string"
},
"text_size_seq": {
"type": "integer"
},
"theme_ids": {
"items": {},
"type": "array"
},
"theme_key_seq": {
"type": "integer"
},
"timezone": {
"type": [
"string",
"null"
]
},
"title_count_mode": {
"type": "string"
},
"user_id": {
"type": "integer"
}
},
"required": [
"user_id",
"mailing_list_mode",
"mailing_list_mode_frequency",
"email_digests",
"email_level",
"email_messages_level",
"external_links_in_new_tab",
"color_scheme_id",
"dark_scheme_id",
"dynamic_favicon",
"enable_quoting",
"enable_defer",
"digest_after_minutes",
"automatically_unpin_topics",
"auto_track_topics_after_msecs",
"notification_level_when_replying",
"new_topic_duration_minutes",
"email_previous_replies",
"email_in_reply_to",
"like_notification_frequency",
"include_tl0_in_digests",
"theme_ids",
"theme_key_seq",
"allow_private_messages",
"enable_allowed_pm_users",
"homepage_id",
"hide_profile_and_presence",
"text_size",
"text_size_seq",
"title_count_mode",
"timezone",
"skip_new_user_tips"
],
"type": "object"
},
"username": {
"type": "string"
},
"watched_category_ids": {
"items": {},
"type": "array"
},
"watched_first_post_category_ids": {
"items": {},
"type": "array"
},
"watched_tags": {
"items": {},
"type": "array"
},
"watching_first_post_tags": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"last_posted_at",
"last_seen_at",
"created_at",
"ignored",
"muted",
"can_ignore_user",
"can_mute_user",
"can_send_private_messages",
"can_send_private_message_to_user",
"trust_level",
"moderator",
"admin",
"title",
"badge_count",
"custom_fields",
"time_read",
"recent_time_read",
"primary_group_id",
"primary_group_name",
"flair_group_id",
"flair_name",
"flair_url",
"flair_bg_color",
"flair_color",
"featured_topic",
"staged",
"can_edit",
"can_edit_username",
"can_edit_email",
"can_edit_name",
"uploaded_avatar_id",
"has_title_badges",
"pending_count",
"profile_view_count",
"second_factor_enabled",
"can_upload_profile_header",
"can_upload_user_card_background",
"post_count",
"can_be_deleted",
"can_delete_all_posts",
"locale",
"muted_category_ids",
"regular_category_ids",
"watched_tags",
"watching_first_post_tags",
"tracked_tags",
"muted_tags",
"tracked_category_ids",
"watched_category_ids",
"watched_first_post_category_ids",
"system_avatar_upload_id",
"system_avatar_template",
"muted_usernames",
"ignored_usernames",
"allowed_pm_usernames",
"mailing_list_posts_per_day",
"can_change_bio",
"can_change_location",
"can_change_website",
"can_change_tracking_preferences",
"user_api_keys",
"user_auth_tokens",
"user_notification_schedule",
"use_logo_small_as_avatar",
"featured_user_badge_ids",
"invited_by",
"groups",
"group_users",
"user_option"
],
"type": "object"
},
"user_badges": {
"items": {},
"type": "array"
}
},
"required": [
"user_badges",
"user"
]
}
}
},
"description": "user response"
}
},
"summary": "Get a user by external_id",
"tags": [
"Users"
]
}
},
"/u/by-external/{provider}/{external_id}.json": {
"get": {
"operationId": "getUserIdentiyProviderExternalId",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Authentication provider name. Can be found in the provider callback\nURL: `/auth/{provider}/callback`",
"in": "path",
"name": "provider",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"user": {
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean"
},
"allowed_pm_usernames": {
"items": {},
"type": "array"
},
"avatar_template": {
"type": "string"
},
"badge_count": {
"type": "integer"
},
"can_be_deleted": {
"type": "boolean"
},
"can_change_bio": {
"type": "boolean"
},
"can_change_location": {
"type": "boolean"
},
"can_change_tracking_preferences": {
"type": "boolean"
},
"can_change_website": {
"type": "boolean"
},
"can_delete_all_posts": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_edit_email": {
"type": "boolean"
},
"can_edit_name": {
"type": "boolean"
},
"can_edit_username": {
"type": "boolean"
},
"can_ignore_user": {
"type": "boolean"
},
"can_mute_user": {
"type": "boolean"
},
"can_send_private_message_to_user": {
"type": "boolean"
},
"can_send_private_messages": {
"type": "boolean"
},
"can_upload_profile_header": {
"type": "boolean"
},
"can_upload_user_card_background": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {
"first_name": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"featured_topic": {
"type": [
"string",
"null"
]
},
"featured_user_badge_ids": {
"items": {},
"type": "array"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_group_id": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"group_users": {
"items": {
"additionalProperties": false,
"properties": {
"group_id": {
"type": "integer"
},
"notification_level": {
"type": "integer"
},
"owner": {
"type": "boolean"
},
"user_id": {
"type": "integer"
}
},
"required": [
"group_id",
"user_id",
"notification_level"
],
"type": "object"
},
"type": "array"
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"has_title_badges": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"ignored": {
"type": "boolean"
},
"ignored_usernames": {
"items": {},
"type": "array"
},
"invited_by": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"type": [
"string",
"null"
]
},
"locale": {
"type": [
"string",
"null"
]
},
"mailing_list_posts_per_day": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"muted": {
"type": "boolean"
},
"muted_category_ids": {
"items": {},
"type": "array"
},
"muted_tags": {
"items": {},
"type": "array"
},
"muted_usernames": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"pending_count": {
"type": "integer"
},
"pending_posts_count": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"profile_view_count": {
"type": "integer"
},
"recent_time_read": {
"type": "integer"
},
"regular_category_ids": {
"items": {},
"type": "array"
},
"second_factor_backup_enabled": {
"type": "boolean"
},
"second_factor_enabled": {
"type": "boolean"
},
"staged": {
"type": "boolean"
},
"system_avatar_template": {
"type": "string"
},
"system_avatar_upload_id": {
"type": [
"string",
"null"
]
},
"time_read": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"tracked_category_ids": {
"items": {},
"type": "array"
},
"tracked_tags": {
"items": {},
"type": "array"
},
"trust_level": {
"type": "integer"
},
"uploaded_avatar_id": {
"type": [
"string",
"null"
]
},
"use_logo_small_as_avatar": {
"type": "boolean"
},
"user_api_keys": {
"type": [
"string",
"null"
]
},
"user_auth_tokens": {
"items": {
"additionalProperties": false,
"properties": {
"browser": {
"type": "string"
},
"client_ip": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device": {
"type": "string"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_active": {
"type": "boolean"
},
"location": {
"type": "string"
},
"os": {
"type": "string"
},
"seen_at": {
"type": "string"
}
},
"required": [
"id",
"client_ip",
"location",
"browser",
"device",
"os",
"icon",
"created_at",
"seen_at",
"is_active"
],
"type": "object"
},
"type": "array"
},
"user_fields": {
"additionalProperties": false,
"properties": {
"1": {
"type": [
"string",
"null"
]
},
"2": {
"type": [
"string",
"null"
]
}
},
"required": [
"1",
"2"
],
"type": "object"
},
"user_notification_schedule": {
"additionalProperties": false,
"properties": {
"day_0_end_time": {
"type": "integer"
},
"day_0_start_time": {
"type": "integer"
},
"day_1_end_time": {
"type": "integer"
},
"day_1_start_time": {
"type": "integer"
},
"day_2_end_time": {
"type": "integer"
},
"day_2_start_time": {
"type": "integer"
},
"day_3_end_time": {
"type": "integer"
},
"day_3_start_time": {
"type": "integer"
},
"day_4_end_time": {
"type": "integer"
},
"day_4_start_time": {
"type": "integer"
},
"day_5_end_time": {
"type": "integer"
},
"day_5_start_time": {
"type": "integer"
},
"day_6_end_time": {
"type": "integer"
},
"day_6_start_time": {
"type": "integer"
},
"enabled": {
"type": "boolean"
}
},
"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"
],
"type": "object"
},
"user_option": {
"additionalProperties": false,
"properties": {
"allow_private_messages": {
"type": "boolean"
},
"auto_track_topics_after_msecs": {
"type": "integer"
},
"automatically_unpin_topics": {
"type": "boolean"
},
"bookmark_auto_delete_preference": {
"type": "integer"
},
"color_scheme_id": {
"type": [
"string",
"null"
]
},
"dark_scheme_id": {
"type": [
"string",
"null"
]
},
"default_calendar": {
"type": "string"
},
"digest_after_minutes": {
"type": "integer"
},
"dynamic_favicon": {
"type": "boolean"
},
"email_digests": {
"type": "boolean"
},
"email_in_reply_to": {
"type": "boolean"
},
"email_level": {
"type": "integer"
},
"email_messages_level": {
"type": "integer"
},
"email_previous_replies": {
"type": "integer"
},
"enable_allowed_pm_users": {
"type": "boolean"
},
"enable_defer": {
"type": "boolean"
},
"enable_quoting": {
"type": "boolean"
},
"external_links_in_new_tab": {
"type": "boolean"
},
"hide_profile_and_presence": {
"type": "boolean"
},
"homepage_id": {
"type": [
"string",
"null"
]
},
"include_tl0_in_digests": {
"type": "boolean"
},
"like_notification_frequency": {
"type": "integer"
},
"mailing_list_mode": {
"type": "boolean"
},
"mailing_list_mode_frequency": {
"type": "integer"
},
"new_topic_duration_minutes": {
"type": "integer"
},
"notification_level_when_replying": {
"type": "integer"
},
"oldest_search_log_date": {
"type": [
"string",
"null"
]
},
"seen_popups": {
"type": [
"array",
"null"
]
},
"sidebar_list_destination": {
"type": "string"
},
"skip_new_user_tips": {
"type": "boolean"
},
"text_size": {
"type": "string"
},
"text_size_seq": {
"type": "integer"
},
"theme_ids": {
"items": {},
"type": "array"
},
"theme_key_seq": {
"type": "integer"
},
"timezone": {
"type": [
"string",
"null"
]
},
"title_count_mode": {
"type": "string"
},
"user_id": {
"type": "integer"
}
},
"required": [
"user_id",
"mailing_list_mode",
"mailing_list_mode_frequency",
"email_digests",
"email_level",
"email_messages_level",
"external_links_in_new_tab",
"color_scheme_id",
"dark_scheme_id",
"dynamic_favicon",
"enable_quoting",
"enable_defer",
"digest_after_minutes",
"automatically_unpin_topics",
"auto_track_topics_after_msecs",
"notification_level_when_replying",
"new_topic_duration_minutes",
"email_previous_replies",
"email_in_reply_to",
"like_notification_frequency",
"include_tl0_in_digests",
"theme_ids",
"theme_key_seq",
"allow_private_messages",
"enable_allowed_pm_users",
"homepage_id",
"hide_profile_and_presence",
"text_size",
"text_size_seq",
"title_count_mode",
"timezone",
"skip_new_user_tips"
],
"type": "object"
},
"username": {
"type": "string"
},
"watched_category_ids": {
"items": {},
"type": "array"
},
"watched_first_post_category_ids": {
"items": {},
"type": "array"
},
"watched_tags": {
"items": {},
"type": "array"
},
"watching_first_post_tags": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"last_posted_at",
"last_seen_at",
"created_at",
"ignored",
"muted",
"can_ignore_user",
"can_mute_user",
"can_send_private_messages",
"can_send_private_message_to_user",
"trust_level",
"moderator",
"admin",
"title",
"badge_count",
"custom_fields",
"time_read",
"recent_time_read",
"primary_group_id",
"primary_group_name",
"flair_group_id",
"flair_name",
"flair_url",
"flair_bg_color",
"flair_color",
"featured_topic",
"staged",
"can_edit",
"can_edit_username",
"can_edit_email",
"can_edit_name",
"uploaded_avatar_id",
"has_title_badges",
"pending_count",
"profile_view_count",
"second_factor_enabled",
"can_upload_profile_header",
"can_upload_user_card_background",
"post_count",
"can_be_deleted",
"can_delete_all_posts",
"locale",
"muted_category_ids",
"regular_category_ids",
"watched_tags",
"watching_first_post_tags",
"tracked_tags",
"muted_tags",
"tracked_category_ids",
"watched_category_ids",
"watched_first_post_category_ids",
"system_avatar_upload_id",
"system_avatar_template",
"muted_usernames",
"ignored_usernames",
"allowed_pm_usernames",
"mailing_list_posts_per_day",
"can_change_bio",
"can_change_location",
"can_change_website",
"can_change_tracking_preferences",
"user_api_keys",
"user_auth_tokens",
"user_notification_schedule",
"use_logo_small_as_avatar",
"featured_user_badge_ids",
"invited_by",
"groups",
"group_users",
"user_option"
],
"type": "object"
},
"user_badges": {
"items": {},
"type": "array"
}
},
"required": [
"user_badges",
"user"
]
}
}
},
"description": "user response"
}
},
"summary": "Get a user by identity provider external ID",
"tags": [
"Users"
]
}
},
"/u/{username}.json": {
"get": {
"operationId": "getUser",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"user": {
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean"
},
"allowed_pm_usernames": {
"items": {},
"type": "array"
},
"avatar_template": {
"type": "string"
},
"badge_count": {
"type": "integer"
},
"can_be_deleted": {
"type": "boolean"
},
"can_change_bio": {
"type": "boolean"
},
"can_change_location": {
"type": "boolean"
},
"can_change_tracking_preferences": {
"type": "boolean"
},
"can_change_website": {
"type": "boolean"
},
"can_delete_all_posts": {
"type": "boolean"
},
"can_edit": {
"type": "boolean"
},
"can_edit_email": {
"type": "boolean"
},
"can_edit_name": {
"type": "boolean"
},
"can_edit_username": {
"type": "boolean"
},
"can_ignore_user": {
"type": "boolean"
},
"can_mute_user": {
"type": "boolean"
},
"can_send_private_message_to_user": {
"type": "boolean"
},
"can_send_private_messages": {
"type": "boolean"
},
"can_upload_profile_header": {
"type": "boolean"
},
"can_upload_user_card_background": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"custom_fields": {
"additionalProperties": false,
"properties": {
"first_name": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"featured_topic": {
"type": [
"string",
"null"
]
},
"featured_user_badge_ids": {
"items": {},
"type": "array"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_group_id": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"group_users": {
"items": {
"additionalProperties": false,
"properties": {
"group_id": {
"type": "integer"
},
"notification_level": {
"type": "integer"
},
"owner": {
"type": "boolean"
},
"user_id": {
"type": "integer"
}
},
"required": [
"group_id",
"user_id",
"notification_level"
],
"type": "object"
},
"type": "array"
},
"groups": {
"items": {
"additionalProperties": false,
"properties": {
"allow_membership_requests": {
"type": "boolean"
},
"automatic": {
"type": "boolean"
},
"bio_cooked": {
"type": [
"string",
"null"
]
},
"bio_excerpt": {
"type": [
"string",
"null"
]
},
"bio_raw": {
"type": [
"string",
"null"
]
},
"can_admin_group": {
"type": "boolean"
},
"can_see_members": {
"type": "boolean"
},
"default_notification_level": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"full_name": {
"type": [
"string",
"null"
]
},
"grant_trust_level": {
"type": [
"string",
"null"
]
},
"has_messages": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"incoming_email": {
"type": [
"string",
"null"
]
},
"members_visibility_level": {
"type": "integer"
},
"membership_request_template": {
"type": [
"string",
"null"
]
},
"mentionable_level": {
"type": "integer"
},
"messageable_level": {
"type": "integer"
},
"name": {
"type": "string"
},
"primary_group": {
"type": "boolean"
},
"public_admission": {
"type": "boolean"
},
"public_exit": {
"type": "boolean"
},
"publish_read_state": {
"type": "boolean"
},
"title": {
"type": [
"string",
"null"
]
},
"user_count": {
"type": "integer"
},
"visibility_level": {
"type": "integer"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"has_title_badges": {
"type": "boolean"
},
"id": {
"type": "integer"
},
"ignored": {
"type": "boolean"
},
"ignored_usernames": {
"items": {},
"type": "array"
},
"invited_by": {
"type": [
"string",
"null"
]
},
"last_posted_at": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"type": [
"string",
"null"
]
},
"locale": {
"type": [
"string",
"null"
]
},
"mailing_list_posts_per_day": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"muted": {
"type": "boolean"
},
"muted_category_ids": {
"items": {},
"type": "array"
},
"muted_tags": {
"items": {},
"type": "array"
},
"muted_usernames": {
"items": {},
"type": "array"
},
"name": {
"type": "string"
},
"pending_count": {
"type": "integer"
},
"pending_posts_count": {
"type": "integer"
},
"post_count": {
"type": "integer"
},
"primary_group_id": {
"type": [
"string",
"null"
]
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"profile_view_count": {
"type": "integer"
},
"recent_time_read": {
"type": "integer"
},
"regular_category_ids": {
"items": {},
"type": "array"
},
"second_factor_backup_enabled": {
"type": "boolean"
},
"second_factor_enabled": {
"type": "boolean"
},
"staged": {
"type": "boolean"
},
"system_avatar_template": {
"type": "string"
},
"system_avatar_upload_id": {
"type": [
"string",
"null"
]
},
"time_read": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"tracked_category_ids": {
"items": {},
"type": "array"
},
"tracked_tags": {
"items": {},
"type": "array"
},
"trust_level": {
"type": "integer"
},
"uploaded_avatar_id": {
"type": [
"string",
"null"
]
},
"use_logo_small_as_avatar": {
"type": "boolean"
},
"user_api_keys": {
"type": [
"string",
"null"
]
},
"user_auth_tokens": {
"items": {
"additionalProperties": false,
"properties": {
"browser": {
"type": "string"
},
"client_ip": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device": {
"type": "string"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_active": {
"type": "boolean"
},
"location": {
"type": "string"
},
"os": {
"type": "string"
},
"seen_at": {
"type": "string"
}
},
"required": [
"id",
"client_ip",
"location",
"browser",
"device",
"os",
"icon",
"created_at",
"seen_at",
"is_active"
],
"type": "object"
},
"type": "array"
},
"user_fields": {
"additionalProperties": false,
"properties": {
"1": {
"type": [
"string",
"null"
]
},
"2": {
"type": [
"string",
"null"
]
}
},
"required": [
"1",
"2"
],
"type": "object"
},
"user_notification_schedule": {
"additionalProperties": false,
"properties": {
"day_0_end_time": {
"type": "integer"
},
"day_0_start_time": {
"type": "integer"
},
"day_1_end_time": {
"type": "integer"
},
"day_1_start_time": {
"type": "integer"
},
"day_2_end_time": {
"type": "integer"
},
"day_2_start_time": {
"type": "integer"
},
"day_3_end_time": {
"type": "integer"
},
"day_3_start_time": {
"type": "integer"
},
"day_4_end_time": {
"type": "integer"
},
"day_4_start_time": {
"type": "integer"
},
"day_5_end_time": {
"type": "integer"
},
"day_5_start_time": {
"type": "integer"
},
"day_6_end_time": {
"type": "integer"
},
"day_6_start_time": {
"type": "integer"
},
"enabled": {
"type": "boolean"
}
},
"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"
],
"type": "object"
},
"user_option": {
"additionalProperties": false,
"properties": {
"allow_private_messages": {
"type": "boolean"
},
"auto_track_topics_after_msecs": {
"type": "integer"
},
"automatically_unpin_topics": {
"type": "boolean"
},
"bookmark_auto_delete_preference": {
"type": "integer"
},
"color_scheme_id": {
"type": [
"string",
"null"
]
},
"dark_scheme_id": {
"type": [
"string",
"null"
]
},
"default_calendar": {
"type": "string"
},
"digest_after_minutes": {
"type": "integer"
},
"dynamic_favicon": {
"type": "boolean"
},
"email_digests": {
"type": "boolean"
},
"email_in_reply_to": {
"type": "boolean"
},
"email_level": {
"type": "integer"
},
"email_messages_level": {
"type": "integer"
},
"email_previous_replies": {
"type": "integer"
},
"enable_allowed_pm_users": {
"type": "boolean"
},
"enable_defer": {
"type": "boolean"
},
"enable_quoting": {
"type": "boolean"
},
"external_links_in_new_tab": {
"type": "boolean"
},
"hide_profile_and_presence": {
"type": "boolean"
},
"homepage_id": {
"type": [
"string",
"null"
]
},
"include_tl0_in_digests": {
"type": "boolean"
},
"like_notification_frequency": {
"type": "integer"
},
"mailing_list_mode": {
"type": "boolean"
},
"mailing_list_mode_frequency": {
"type": "integer"
},
"new_topic_duration_minutes": {
"type": "integer"
},
"notification_level_when_replying": {
"type": "integer"
},
"oldest_search_log_date": {
"type": [
"string",
"null"
]
},
"seen_popups": {
"type": [
"array",
"null"
]
},
"sidebar_list_destination": {
"type": "string"
},
"skip_new_user_tips": {
"type": "boolean"
},
"text_size": {
"type": "string"
},
"text_size_seq": {
"type": "integer"
},
"theme_ids": {
"items": {},
"type": "array"
},
"theme_key_seq": {
"type": "integer"
},
"timezone": {
"type": [
"string",
"null"
]
},
"title_count_mode": {
"type": "string"
},
"user_id": {
"type": "integer"
}
},
"required": [
"user_id",
"mailing_list_mode",
"mailing_list_mode_frequency",
"email_digests",
"email_level",
"email_messages_level",
"external_links_in_new_tab",
"color_scheme_id",
"dark_scheme_id",
"dynamic_favicon",
"enable_quoting",
"enable_defer",
"digest_after_minutes",
"automatically_unpin_topics",
"auto_track_topics_after_msecs",
"notification_level_when_replying",
"new_topic_duration_minutes",
"email_previous_replies",
"email_in_reply_to",
"like_notification_frequency",
"include_tl0_in_digests",
"theme_ids",
"theme_key_seq",
"allow_private_messages",
"enable_allowed_pm_users",
"homepage_id",
"hide_profile_and_presence",
"text_size",
"text_size_seq",
"title_count_mode",
"timezone",
"skip_new_user_tips"
],
"type": "object"
},
"username": {
"type": "string"
},
"watched_category_ids": {
"items": {},
"type": "array"
},
"watched_first_post_category_ids": {
"items": {},
"type": "array"
},
"watched_tags": {
"items": {},
"type": "array"
},
"watching_first_post_tags": {
"items": {},
"type": "array"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"last_posted_at",
"last_seen_at",
"created_at",
"ignored",
"muted",
"can_ignore_user",
"can_mute_user",
"can_send_private_messages",
"can_send_private_message_to_user",
"trust_level",
"moderator",
"admin",
"title",
"badge_count",
"custom_fields",
"time_read",
"recent_time_read",
"primary_group_id",
"primary_group_name",
"flair_group_id",
"flair_name",
"flair_url",
"flair_bg_color",
"flair_color",
"featured_topic",
"staged",
"can_edit",
"can_edit_username",
"can_edit_email",
"can_edit_name",
"uploaded_avatar_id",
"has_title_badges",
"pending_count",
"profile_view_count",
"second_factor_enabled",
"can_upload_profile_header",
"can_upload_user_card_background",
"post_count",
"can_be_deleted",
"can_delete_all_posts",
"locale",
"muted_category_ids",
"regular_category_ids",
"watched_tags",
"watching_first_post_tags",
"tracked_tags",
"muted_tags",
"tracked_category_ids",
"watched_category_ids",
"watched_first_post_category_ids",
"system_avatar_upload_id",
"system_avatar_template",
"muted_usernames",
"ignored_usernames",
"allowed_pm_usernames",
"mailing_list_posts_per_day",
"can_change_bio",
"can_change_location",
"can_change_website",
"can_change_tracking_preferences",
"user_api_keys",
"user_auth_tokens",
"user_notification_schedule",
"use_logo_small_as_avatar",
"featured_user_badge_ids",
"invited_by",
"groups",
"group_users",
"user_option"
],
"type": "object"
},
"user_badges": {
"items": {},
"type": "array"
}
},
"required": [
"user_badges",
"user"
]
}
}
},
"description": "user response"
}
},
"summary": "Get a single user by username",
"tags": [
"Users"
]
},
"put": {
"operationId": "updateUser",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"email": {
"type": "string"
},
"external_ids": {
"type": "object"
},
"name": {
"type": "string"
},
"password": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"type": "string"
},
"user": {
"type": "object"
}
},
"required": [
"success",
"user"
]
}
}
},
"description": "user updated"
}
},
"summary": "Update a user",
"tags": [
"Users"
]
}
},
"/u/{username}/emails.json": {
"get": {
"operationId": "getUserEmails",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"associated_accounts": {
"items": {},
"type": "array"
},
"email": {
"type": "string"
},
"secondary_emails": {
"items": {},
"type": "array"
},
"unconfirmed_emails": {
"items": {},
"type": "array"
}
},
"required": [
"email",
"secondary_emails",
"unconfirmed_emails",
"associated_accounts"
]
}
}
},
"description": "success response"
}
},
"summary": "Get email addresses belonging to a user",
"tags": [
"Users"
]
}
},
"/u/{username}/preferences/avatar/pick.json": {
"put": {
"operationId": "updateAvatar",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"uploaded",
"custom",
"gravatar",
"system"
],
"type": "string"
},
"upload_id": {
"type": "integer"
}
},
"required": [
"upload_id",
"type"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"required": [
"success"
]
}
}
},
"description": "avatar updated"
}
},
"summary": "Update avatar",
"tags": [
"Users"
]
}
},
"/u/{username}/preferences/email.json": {
"put": {
"operationId": "updateEmail",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"type": "string"
}
},
"required": [
"email"
]
}
}
}
},
"responses": {
"200": {
"description": "email updated"
}
},
"summary": "Update email",
"tags": [
"Users"
]
}
},
"/u/{username}/preferences/username.json": {
"put": {
"operationId": "updateUsername",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"new_username": {
"type": "string"
}
},
"required": [
"new_username"
]
}
}
}
},
"responses": {
"200": {
"description": "username updated"
}
},
"summary": "Update username",
"tags": [
"Users"
]
}
},
"/uploads.json": {
"post": {
"operationId": "createUpload",
"parameters": [],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"additionalProperties": false,
"properties": {
"file": {},
"synchronous": {
"description": "Use this flag to return an id and url",
"type": "boolean"
},
"type": {
"enum": [
"avatar",
"profile_background",
"card_background",
"custom_emoji",
"composer"
],
"type": "string"
},
"user_id": {
"description": "required if uploading an avatar",
"type": "integer"
}
},
"required": [
"type"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"dominant_color": {
"type": [
"string",
"null"
]
},
"extension": {
"type": "string"
},
"filesize": {
"type": "integer"
},
"height": {
"type": "integer"
},
"human_filesize": {
"type": "string"
},
"id": {
"type": "integer"
},
"original_filename": {
"type": "string"
},
"retain_hours": {
"type": [
"string",
"null"
]
},
"short_path": {
"type": "string"
},
"short_url": {
"type": "string"
},
"thumbnail_height": {
"type": "integer"
},
"thumbnail_width": {
"type": "integer"
},
"url": {
"type": "string"
},
"width": {
"type": "integer"
}
},
"required": [
"id",
"url",
"original_filename",
"filesize",
"width",
"height",
"thumbnail_width",
"thumbnail_height",
"extension",
"short_url",
"short_path",
"retain_hours",
"human_filesize"
]
}
}
},
"description": "file uploaded"
}
},
"summary": "Creates an upload",
"tags": [
"Uploads"
]
}
},
"/uploads/abort-multipart.json": {
"post": {
"description": "This endpoint aborts the multipart upload initiated with /create-multipart.\nThis should be used when cancelling the upload. It does not matter if parts\nwere already uploaded into the external storage provider.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "abortMultipart",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"external_upload_identifier": {
"description": "The identifier of the multipart upload in the external\nstorage provider. This is the multipart upload_id in AWS S3.",
"examples": [
"84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ"
],
"type": "string"
}
},
"required": [
"external_upload_identifier"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"success": {
"examples": [
"OK"
],
"type": "string"
}
},
"required": [
"success"
]
}
}
},
"description": "external upload initialized"
}
},
"summary": "Abort multipart upload",
"tags": [
"Uploads"
]
}
},
"/uploads/batch-presign-multipart-parts.json": {
"post": {
"description": "Multipart uploads are uploaded in chunks or parts to individual presigned\nURLs, similar to the one generated by /generate-presigned-put. The part\nnumbers provided must be between 1 and 10000. The total number of parts\nwill depend on the chunk size in bytes that you intend to use to upload\neach chunk. For example a 12MB file may have 2 5MB chunks and a final\n2MB chunk, for part numbers 1, 2, and 3.\n\nThis endpoint will return a presigned URL for each part number provided,\nwhich you can then use to send PUT requests for the binary chunk corresponding\nto that part. When the part is uploaded, the provider should return an\nETag for the part, and this should be stored along with the part number,\nbecause this is needed to complete the multipart upload.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "batchPresignMultipartParts",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"part_numbers": {
"description": "The part numbers to generate the presigned URLs for,\nmust be between 1 and 10000.",
"examples": [
[
1,
2,
3
]
],
"type": "array"
},
"unique_identifier": {
"description": "The unique identifier returned in the original /create-multipart\nrequest.",
"examples": [
"66e86218-80d9-4bda-b4d5-2b6def968705"
],
"type": "string"
}
},
"required": [
"part_numbers",
"unique_identifier"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"presigned_urls": {
"description": "The presigned URLs for each part number, which has\nthe part numbers as keys.",
"examples": [
{
"1": "https://discourse-martin-uploads-test.s3.us-east-2.amazonaws.com/temp/uploads/default/123abc/123abc.jpg?partNumber=1&uploadId=123456abcd&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test&X-Amz-Date=20211222T012336Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123"
}
],
"type": "object"
}
},
"required": [
"presigned_urls"
]
}
}
},
"description": "external upload initialized"
}
},
"summary": "Generates batches of presigned URLs for multipart parts",
"tags": [
"Uploads"
]
}
},
"/uploads/complete-external-upload.json": {
"post": {
"description": "Completes an external upload initialized with /get-presigned-put. The\nfile will be moved from its temporary location in external storage to\na final destination in the S3 bucket. An Upload record will also be\ncreated in the database in most cases.\n\nIf a sha1-checksum was provided in the initial request it will also\nbe compared with the uploaded file in storage to make sure the same\nfile was uploaded. The file size will be compared for the same reason.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "completeExternalUpload",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"for_private_message": {
"description": "Optionally set this to true if the upload is for a\nprivate message.",
"examples": [
"true"
],
"type": "string"
},
"for_site_setting": {
"description": "Optionally set this to true if the upload is for a\nsite setting.",
"examples": [
"true"
],
"type": "string"
},
"pasted": {
"description": "Optionally set this to true if the upload was pasted\ninto the upload area. This will convert PNG files to JPEG.",
"examples": [
"true"
],
"type": "string"
},
"unique_identifier": {
"description": "The unique identifier returned in the original /generate-presigned-put\nrequest.",
"examples": [
"66e86218-80d9-4bda-b4d5-2b6def968705"
],
"type": "string"
}
},
"required": [
"unique_identifier"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"dominant_color": {
"type": [
"string",
"null"
]
},
"extension": {
"type": "string"
},
"filesize": {
"type": "integer"
},
"height": {
"type": "integer"
},
"human_filesize": {
"type": "string"
},
"id": {
"type": "integer"
},
"original_filename": {
"type": "string"
},
"retain_hours": {
"type": [
"string",
"null"
]
},
"short_path": {
"type": "string"
},
"short_url": {
"type": "string"
},
"thumbnail_height": {
"type": "integer"
},
"thumbnail_width": {
"type": "integer"
},
"url": {
"type": "string"
},
"width": {
"type": "integer"
}
},
"required": [
"id",
"url",
"original_filename",
"filesize",
"width",
"height",
"thumbnail_width",
"thumbnail_height",
"extension",
"short_url",
"short_path",
"retain_hours",
"human_filesize"
]
}
}
},
"description": "external upload initialized"
}
},
"summary": "Completes a direct external upload",
"tags": [
"Uploads"
]
}
},
"/uploads/complete-multipart.json": {
"post": {
"description": "Completes the multipart upload in the external store, and copies the\nfile from its temporary location to its final location in the store.\nAll of the parts must have been uploaded to the external storage provider.\nAn Upload record will be completed in most cases once the file is copied\nto its final location.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "completeMultipart",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"parts": {
"description": "All of the part numbers and their corresponding ETags\nthat have been uploaded must be provided.",
"examples": [
[
{
"etag": "0c376dcfcc2606f4335bbc732de93344",
"part_number": 1
},
{
"etag": "09ert8cfcc2606f4335bbc732de91122",
"part_number": 2
}
]
],
"type": "array"
},
"unique_identifier": {
"description": "The unique identifier returned in the original /create-multipart\nrequest.",
"examples": [
"66e86218-80d9-4bda-b4d5-2b6def968705"
],
"type": "string"
}
},
"required": [
"unique_identifier",
"parts"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"dominant_color": {
"type": [
"string",
"null"
]
},
"extension": {
"type": "string"
},
"filesize": {
"type": "integer"
},
"height": {
"type": "integer"
},
"human_filesize": {
"type": "string"
},
"id": {
"type": "integer"
},
"original_filename": {
"type": "string"
},
"retain_hours": {
"type": [
"string",
"null"
]
},
"short_path": {
"type": "string"
},
"short_url": {
"type": "string"
},
"thumbnail_height": {
"type": "integer"
},
"thumbnail_width": {
"type": "integer"
},
"url": {
"type": "string"
},
"width": {
"type": "integer"
}
},
"required": [
"id",
"url",
"original_filename",
"filesize",
"width",
"height",
"thumbnail_width",
"thumbnail_height",
"extension",
"short_url",
"short_path",
"retain_hours",
"human_filesize"
]
}
}
},
"description": "external upload initialized"
}
},
"summary": "Complete multipart upload",
"tags": [
"Uploads"
]
}
},
"/uploads/create-multipart.json": {
"post": {
"description": "Creates a multipart upload in the external storage provider, storing\na temporary reference to the external upload similar to /get-presigned-put.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "createMultipartUpload",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"file_name": {
"examples": [
"IMG_2021.jpeg"
],
"type": "string"
},
"file_size": {
"description": "File size should be represented in bytes.",
"examples": [
4096
],
"type": "integer"
},
"metadata": {
"additionalProperties": false,
"properties": {
"sha1-checksum": {
"description": "The SHA1 checksum of the upload binary blob. Optionally\nbe provided and serves as an additional security check when\nlater processing the file in complete-external-upload endpoint.",
"type": "string"
}
},
"type": "object"
},
"upload_type": {
"enum": [
"avatar",
"profile_background",
"card_background",
"custom_emoji",
"composer"
],
"type": "string"
}
},
"required": [
"upload_type",
"file_name",
"file_size"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"external_upload_identifier": {
"description": "The identifier of the multipart upload in the external\nstorage provider. This is the multipart upload_id in AWS S3.",
"examples": [
"84x83tmxy398t3y._Q_z8CoJYVr69bE6D7f8J6Oo0434QquLFoYdGVerWFx9X5HDEI_TP_95c34n853495x35345394.d.ghQ"
],
"type": "string"
},
"key": {
"description": "The path of the temporary file on the external storage\nservice.",
"examples": [
"temp/site/uploads/default/12345/67890.jpg"
],
"type": "string"
},
"unique_identifier": {
"description": "A unique string that identifies the external upload.\nThis must be stored and then sent in the /complete-multipart\nand /batch-presign-multipart-parts endpoints.",
"examples": [
"66e86218-80d9-4bda-b4d5-2b6def968705"
],
"type": "string"
}
},
"required": [
"external_upload_identifier",
"key",
"unique_identifier"
]
}
}
},
"description": "external upload initialized"
}
},
"summary": "Creates a multipart external upload",
"tags": [
"Uploads"
]
}
},
"/uploads/generate-presigned-put.json": {
"post": {
"description": "Direct external uploads bypass the usual method of creating uploads\nvia the POST /uploads route, and upload directly to an external provider,\nwhich by default is S3. This route begins the process, and will return\na unique identifier for the external upload as well as a presigned URL\nwhich is where the file binary blob should be uploaded to.\n\nOnce the upload is complete to the external service, you must call the\nPOST /complete-external-upload route using the unique identifier returned\nby this route, which will create any required Upload record in the Discourse\ndatabase and also move file from its temporary location to the final\ndestination in the external storage service.\n\nYou must have the correct permissions and CORS settings configured in your\nexternal provider. We support AWS S3 as the default. See:\n\nhttps://meta.discourse.org/t/-/210469#s3-multipart-direct-uploads-4.\n\nAn external file store must be set up and `enable_direct_s3_uploads` must\nbe set to true for this endpoint to function.\n\n",
"operationId": "generatePresignedPut",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"file_name": {
"examples": [
"IMG_2021.jpeg"
],
"type": "string"
},
"file_size": {
"description": "File size should be represented in bytes.",
"examples": [
4096
],
"type": "integer"
},
"metadata": {
"additionalProperties": false,
"properties": {
"sha1-checksum": {
"description": "The SHA1 checksum of the upload binary blob. Optionally\nbe provided and serves as an additional security check when\nlater processing the file in complete-external-upload endpoint.",
"type": "string"
}
},
"type": "object"
},
"type": {
"enum": [
"avatar",
"profile_background",
"card_background",
"custom_emoji",
"composer"
],
"type": "string"
}
},
"required": [
"type",
"file_name",
"file_size"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"key": {
"description": "The path of the temporary file on the external storage\nservice.",
"examples": [
"temp/site/uploads/default/12345/67890.jpg"
],
"type": "string"
},
"unique_identifier": {
"description": "A unique string that identifies the external upload.\nThis must be stored and then sent in the /complete-external-upload\nendpoint to complete the direct upload.",
"examples": [
"66e86218-80d9-4bda-b4d5-2b6def968705"
],
"type": "string"
},
"url": {
"description": "A presigned PUT URL which must be used to upload\nthe file binary blob to.",
"examples": [
"https://file-uploads.s3.us-west-2.amazonaws.com/temp/site/uploads/default/123/456.jpg?x-amz-acl=private&x-amz-meta-sha1-checksum=sha1&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AAAAus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20211221T011246Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=12345678"
],
"type": "string"
}
}
}
}
},
"description": "external upload initialized"
}
},
"summary": "Initiates a direct external upload",
"tags": [
"Uploads"
]
}
},
"/user-badges/{username}.json": {
"get": {
"operationId": "listUserBadges",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"badge_types": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"sort_order": {
"type": "integer"
}
},
"required": [
"id",
"name",
"sort_order"
],
"type": "object"
},
"type": "array"
},
"badges": {
"items": {
"additionalProperties": false,
"properties": {
"allow_title": {
"type": "boolean"
},
"badge_grouping_id": {
"type": "integer"
},
"badge_type_id": {
"type": "integer"
},
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"grant_count": {
"type": "integer"
},
"icon": {
"type": "string"
},
"id": {
"type": "integer"
},
"image_url": {
"type": [
"string",
"null"
]
},
"listable": {
"type": "boolean"
},
"manually_grantable": {
"type": "boolean"
},
"multiple_grant": {
"type": "boolean"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"system": {
"type": "boolean"
}
},
"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"
],
"type": "object"
},
"type": "array"
},
"granted_bies": {
"items": {
"additionalProperties": false,
"properties": {
"admin": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"flair_name": {
"type": [
"string",
"null"
]
},
"id": {
"type": "integer"
},
"moderator": {
"type": "boolean"
},
"name": {
"type": "string"
},
"trust_level": {
"type": "integer"
},
"username": {
"type": "string"
}
},
"required": [
"id",
"username",
"name",
"avatar_template",
"flair_name",
"admin",
"moderator",
"trust_level"
],
"type": "object"
},
"type": "array"
},
"user_badges": {
"items": {
"additionalProperties": false,
"properties": {
"badge_id": {
"type": "integer"
},
"can_favorite": {
"type": "boolean"
},
"granted_at": {
"type": "string"
},
"granted_by_id": {
"type": "integer"
},
"grouping_position": {
"type": "integer"
},
"id": {
"type": "integer"
},
"is_favorite": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"granted_at",
"grouping_position",
"is_favorite",
"can_favorite",
"badge_id",
"granted_by_id"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"user_badges"
]
}
}
},
"description": "success response"
}
},
"summary": "List badges for a user",
"tags": [
"Badges",
"Users"
]
}
},
"/user_actions.json": {
"get": {
"operationId": "listUserActions",
"parameters": [
{
"in": "query",
"name": "offset",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "filter",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"user_actions": {
"items": {
"additionalProperties": false,
"properties": {
"acting_avatar_template": {
"type": "string"
},
"acting_name": {
"type": [
"string",
"null"
]
},
"acting_user_id": {
"type": "integer"
},
"acting_username": {
"type": "string"
},
"action_code": {
"type": [
"string",
"null"
]
},
"action_type": {
"type": "integer"
},
"archived": {
"type": "boolean"
},
"avatar_template": {
"type": "string"
},
"category_id": {
"type": "integer"
},
"closed": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"deleted": {
"type": "boolean"
},
"excerpt": {
"type": "string"
},
"hidden": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"post_id": {
"type": [
"string",
"null"
]
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": [
"string",
"null"
]
},
"slug": {
"type": "string"
},
"target_name": {
"type": [
"string",
"null"
]
},
"target_user_id": {
"type": "integer"
},
"target_username": {
"type": "string"
},
"title": {
"type": "string"
},
"topic_id": {
"type": "integer"
},
"user_id": {
"type": "integer"
},
"username": {
"type": "string"
}
},
"required": [
"excerpt",
"action_type",
"created_at",
"avatar_template",
"acting_avatar_template",
"slug",
"topic_id",
"target_user_id",
"target_name",
"target_username",
"post_number",
"post_id",
"username",
"name",
"user_id",
"acting_username",
"acting_name",
"acting_user_id",
"title",
"deleted",
"hidden",
"post_type",
"action_code",
"category_id",
"closed",
"archived"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"user_actions"
]
}
}
},
"description": "response"
}
},
"summary": "Get a list of user actions",
"tags": [
"Users"
]
}
},
"/user_avatar/{username}/refresh_gravatar.json": {
"post": {
"operationId": "refreshGravatar",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"gravatar_avatar_template": {
"type": [
"string",
"null"
]
},
"gravatar_upload_id": {
"type": [
"integer",
"null"
]
}
},
"required": [
"gravatar_upload_id",
"gravatar_avatar_template"
]
}
}
},
"description": "response"
}
},
"summary": "Refresh gravatar",
"tags": [
"Users",
"Admin"
]
}
},
"/users.json": {
"post": {
"operationId": "createUser",
"parameters": [
{
"in": "header",
"name": "Api-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Api-Username",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"active": {
"description": "This param requires an api key in the request header\nor it will be ignored",
"type": "boolean"
},
"approved": {
"type": "boolean"
},
"email": {
"type": "string"
},
"external_ids": {
"type": "object"
},
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"user_fields[1]": {
"type": "boolean"
},
"username": {
"type": "string"
}
},
"required": [
"name",
"email",
"password",
"username"
]
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"active": {
"type": "boolean"
},
"message": {
"type": "string"
},
"success": {
"type": "boolean"
},
"user_id": {
"type": "integer"
}
},
"required": [
"success",
"active",
"message"
]
}
}
},
"description": "user created"
}
},
"summary": "Creates a user",
"tags": [
"Users"
]
}
},
"/users/password-reset/{token}.json": {
"put": {
"operationId": "changePassword",
"parameters": [
{
"in": "path",
"name": "token",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"password": {
"type": "string"
},
"username": {
"type": "string"
}
},
"required": [
"username",
"password"
]
}
}
}
},
"responses": {
"200": {
"description": "success response"
}
},
"summary": "Change password",
"tags": [
"Users"
]
}
}
},
"components": {
"schemas": {}
}
}