# Site collection categories
This endpoint lets you manage your knowledge base categories. Categories can be retrieved without authentication.
# The category object
id integer
The system-generated ID of the category.
collection_id integer
The system-generated ID of the collection.
name string
The name of the category in the requested locale.
summary string
A short summary of the category in the requested locale.
source_locale string
The source locale of the category, which determines the main translation other translations should be based on.
locale string
The locale of the current translation being served.
sort_order decimal
The position of the category in a sorted list. This value can be either incremental (automatically assigned), or custom.
articles_count integer
The number of articles under this category.
collection_id integer
The system-generated ID of the collection.
collection object expandable
The collection object attached to the article.
views_count integer
The total views of this category.
translations array
The list of translations of the category.
Show child attributestranslations.[en, es, ...] object
The translation object.
Show child attributes[en, es, ...].id integer
The system-generated ID of the translation.
[en, es, ...].locale string
The locale of the translation.
[en, es, ...].name string
The name of the category.
[en, es, ...].summary string
A short summary of the category.
created_at string
The timestamp when the category was created.
updated_at string
The timestamp when the category was last updated.
# The category object
{
"id": 3,
"name": "Sample category",
"summary": "This is a summary of the category.",
"source_locale": "en",
"locale": "en",
"sort_order": 1.5,
"articles_count": 0,
"collection_id": 1,
"collection": {...},
"views_count": 0,
"translations": {
"en": {
"id": 5,
"locale": "en",
"name": "Sample category",
"summary": "This is a summary of the category.",
},
"es-PR": {
"id": 6,
"locale": "es-PR",
"name": "Ejemplo de categoría",
"summary": "Resumen del categoría",
}
}
}
# Create an category
collection_id integer required
The system-generated ID of the collection.
source_locale string required
The source locale of the category, which determines the main translation other translations should be based on.
sort_order decimal optional
The position of the category in a sorted list. New categories will be placed in the end of the list when this attribute is empty.
translations array
The list of translations of the category.
Show child attributestranslations.[en, es, ...] object
The translation object.
Show child attributes[en, es, ...].name string required for source locale
The name of the category.
[en, es, ...].summary string optional
A short summary of the category.
# Sample request
curl https://www.yourdomain.com/api/v1/site/1/categories \
--request POST \
-H "Accept: application/json" \
-H "Authorization: Bearer <access-token>" \
-d collection_id=1 \
-d source_locale="en" \
-d sort_order=3 \
-d translations[en][name]="Sample category" \
-d translations[en][summary]="This is a summary of the category" \
-d translations[es-PR][name]="Ejemplo de artículo" \
-d translations[es-PR][summary]="Resumen del artículo." \
# Sample successful response
{
"data": {
"id": 3,
"name": "Sample category",
"summary": "This is a summary of the category",
"source_locale": "en",
"locale": "en",
"sort_order": 1.5,
"articles_count": 0,
"collection_id": 1,
"collection": {...},
"views_count": 0,
"translations": {
"en": {
"id": 5,
"locale": "en",
"name": "Sample category",
"summary": "This is a summary of the category",
},
"es-PR": {
"id": 6,
"locale": "es-PR",
"name": "Ejemplo de artículo",
"summary": "Resumen del artículo",
}
}
}
}
# Retrieve an category
# Sample request
curl https://www.yourdomain.com/api/v1/sites/1/categories/1 \
-H "Accept: application/json" \
-H "Authorization: Bearer <access-token>" \
-G
# Sample successful response
{
"data": {
"id": 3,
"name": "Sample category",
"summary": "This is a summary of the category",
"source_locale": "en",
"locale": "en",
"sort_order": 1.5,
"collection_id": 1,
"collection": {...},
"views_count": 0,
"translations": {
"en": {
"id": 5,
"locale": "en",
"name": "Sample category",
"summary": "This is a summary of the category",
},
"es-PR": {
"id": 6,
"locale": "es-PR",
"name": "Ejemplo de artículo",
"summary": "Resumen del artículo",
}
}
}
}
# Update an category
collection_id integer required
The system-generated ID of the collection.
source_locale string required
The source locale of the category, which determines the main translation other translations should be based on.
category_id integer required
The system-generated ID of the category.
sort_order decimal optional
The position of the category in a sorted list. New categories will be placed in the end of the list when this attribute is empty.
translations array
The list of translations of the category.
Show child attributestranslations.[en, es, ...] object
The translation object.
Show child attributes[en, es, ...].name string required for source locale
The name of the category.
[en, es, ...].summary string optional
A short summary of the category.
# Sample request
curl https://www.yourdomain.com/api/v1/sites/1/categories/1 \
--request PUT \
-H "Accept: application/json" \
-H "Authorization: Bearer <access-token>" \
-d collection_id=1 \
-d source_locale="en" \
-d sort_order=3 \
-d translations[en][name]="Sample category" \
-d translations[en][summary]="This is a summary of the category" \
-d translations[es-PR][name]="Ejemplo de artículo" \
-d translations[es-PR][summary]="Resumen del artículo." \
# Sample successful response
{
"data": {
"id": 3,
"site_id": 1,
"name": "Sample category",
"summary": "This is a summary of the category",
"source_locale": "en",
"locale": "en",
"sort_order": 1.5,
"articles_count": 0,
"collection_id": 1,
"collection": {...},
"views_count": 0,
"translations": {
"en": {
"id": 5,
"locale": "en",
"name": "Sample category",
"summary": "This is a summary of the category",
},
"es-PR": {
"id": 6,
"locale": "es-PR",
"name": "Ejemplo de artículo",
"summary": "Resumen del artículo",
}
}
}
}
# Delete an category
curl https://www.yourdomain.com/api/v1/sites/1/categories/1 \
--request DELETE
-H "Accept: application/json" \
-H "Authorization: Bearer <access-token>"
If successful, the above request will return an empty response with 204 HTTP status code.
# List all categories
# Parameters
collection_id integer optional
A filter on the list based on the article's
collection_idfield.sort_by enum: sort_order optional
A sort on the list based on the provided category's field.
sort_type enum: desc, asc optional
The type of the sort to perform.
# Sample request
curl https://www.yourdomain.com/api/v1/sites/1/categories \
-H "Accept: application/json" \
-H "Authorization: Bearer <access-token>" \
-G
# Sample successful response
{
"data": [
{
"id": 3,
"name": "Sample category",
"summary": "This is a summary of the category",
"source_locale": "en",
"locale": "en",
"sort_order": 1.5,
"articles_count": 0,
"collection_id": 1,
"collection": {...},
"views_count": 0,
"translations": {
"en": {
"id": 5,
"locale": "en",
"name": "Sample category",
"summary": "This is a summary of the category",
},
"es-PR": {
"id": 6,
"locale": "es-PR",
"name": "Ejemplo de artículo",
"summary": "Resumen del artículo",
}
}
},
{...}
]
}