Discourse Tags API
The Tags API from Discourse — 4 operation(s) for tags.
OpenAPI Specification
openapi: 3.1.0
info:
title: Discourse API Documentation Admin Tags API
x-logo:
url: https://docs.discourse.org/logo.svg
version: latest
description: 'This page contains the documentation on how to use Discourse through API calls.
> Note: For any endpoints not listed you can follow the
[reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)
guide to figure out how to use an API endpoint.
### Request Content-Type
The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,
`multipart/form-data`, or `application/json`.
### Endpoint Names and Response Content-Type
Most API endpoints provide the same content as their HTML counterparts. For example
the URL `/categories` serves a list of categories, the `/categories.json` API provides the
same information in JSON format.
Instead of sending API requests to `/categories.json` you may also send them to `/categories`
and add an `Accept: application/json` header to the request to get the JSON response.
Sending requests with the `Accept` header is necessary if you want to use URLs
for related endpoints returned by the API, such as pagination URLs.
These URLs are returned without the `.json` prefix so you need to add the header in
order to get the correct response format.
### Authentication
Some endpoints do not require any authentication, pretty much anything else will
require you to be authenticated.
To become authenticated you will need to create an API Key from the admin panel.
Once you have your API Key you can pass it in along with your API Username
as an HTTP header like this:
```
curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system"
```
and this is how POST requests will look:
```
curl -X POST "http://127.0.0.1:3000/categories" \
-H "Content-Type: multipart/form-data;" \
-H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
-H "Api-Username: system" \
-F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
-F "color=49d9e9" \
-F "text_color=f0fcfd"
```
### Boolean values
If an endpoint accepts a boolean be sure to specify it as a lowercase
`true` or `false` value unless noted otherwise.
'
license:
name: MIT
url: https://docs.discourse.org/LICENSE.txt
servers:
- url: https://{defaultHost}
variables:
defaultHost:
default: discourse.example.com
tags:
- name: Tags
paths:
/tag_groups.json:
get:
summary: Get a list of tag groups
tags:
- Tags
operationId: listTagGroups
responses:
'200':
description: tags
content:
application/json:
schema:
additionalProperties: false
properties:
tag_groups:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
tags:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
slug:
type: string
required:
- id
- name
- slug
parent_tag:
type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
name:
type: string
slug:
type: string
required:
- id
- name
- slug
one_per_topic:
type: boolean
permissions:
type: object
additionalProperties:
type: integer
required:
- id
- name
- tags
- parent_tag
- one_per_topic
- permissions
required:
- tag_groups
post:
summary: Creates a tag group
tags:
- Tags
operationId: createTagGroup
parameters: []
responses:
'200':
description: tag group created
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
tag_group:
type: object
properties:
id:
type: integer
name:
type: string
tags:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
required:
- id
- name
- slug
parent_tag:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
required:
- id
- name
- slug
one_per_topic:
type: boolean
permissions:
type: object
required:
- id
- name
- tags
- parent_tag
- one_per_topic
- permissions
required:
- tag_group
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
name:
type: string
required:
- name
/tag_groups/{id}.json:
get:
summary: Get a single tag group
tags:
- Tags
operationId: getTagGroup
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: notifications
content:
application/json:
schema:
type: object
properties:
tag_group:
type: object
properties:
id:
type: integer
name:
type: string
tag_names:
type: array
items: {}
parent_tag_name:
type: array
items: {}
one_per_topic:
type: boolean
permissions:
type: object
properties:
everyone:
type: integer
put:
summary: Update tag group
tags:
- Tags
operationId: updateTagGroup
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
description: Tag group updated
content:
application/json:
schema:
type: object
properties:
success:
type: string
tag_group:
type: object
properties:
id:
type: integer
name:
type: string
tag_names:
type: array
items: {}
parent_tag_name:
type: array
items: {}
one_per_topic:
type: boolean
permissions:
type: object
properties:
everyone:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
/tags.json:
get:
summary: Get a list of tags
tags:
- Tags
operationId: listTags
responses:
'200':
description: notifications
content:
application/json:
schema:
type: object
properties:
tags:
type: array
items:
type: object
properties:
id:
type: integer
text:
type: string
name:
type: string
count:
type: integer
pm_count:
type: integer
target_tag:
type:
- string
- 'null'
extras:
type: object
properties:
categories:
type: array
items: {}
/tag/{name}.json:
get:
summary: Get a specific tag
tags:
- Tags
operationId: getTag
parameters:
- name: name
in: path
schema:
type: string
required: true
responses:
'200':
description: notifications
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
type: object
properties:
id:
type: integer
username:
type: string
name:
type:
- string
- 'null'
avatar_template:
type: string
primary_groups:
type: array
items: {}
topic_list:
type: object
properties:
can_create_topic:
type: boolean
draft:
type:
- string
- 'null'
draft_key:
type: string
draft_sequence:
type: integer
per_page:
type: integer
tags:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
topic_count:
type: integer
staff:
type: boolean
topics:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
fancy_title:
type: string
slug:
type: string
posts_count:
type: integer
reply_count:
type: integer
highest_post_number:
type: integer
image_url:
type:
- string
- 'null'
created_at:
type: string
last_posted_at:
type: string
bumped:
type: boolean
bumped_at:
type: string
archetype:
type: string
unseen:
type: boolean
last_read_post_number:
type: integer
unread_posts:
type: integer
pinned:
type: boolean
unpinned:
type:
- string
- 'null'
visible:
type: boolean
closed:
type: boolean
archived:
type: boolean
notification_level:
type: integer
bookmarked:
type: boolean
liked:
type: boolean
tags:
type: array
items: {}
views:
type: integer
like_count:
type: integer
has_summary:
type: boolean
last_poster_username:
type: string
category_id:
type: integer
pinned_globally:
type: boolean
featured_link:
type:
- string
- 'null'
posters:
type: array
items:
type: object
properties:
extras:
type: string
description:
type: string
user_id:
type: integer
primary_group_id:
type:
- integer
- 'null'