Knowledge base Categories

Creating a category

POST https://api.groovehq.com/v1/kb/:knowledge_base_id/categories

Parameters

Name	Type	Required	Default	Notes
article_ids	array	No		The array of category IDs to associate with this category.
author_id	string	No	OAuth user	The ID of the user set as the author of the category.
description	string	No		The description of the category.
meta_description	string	No	`description`	The meta tag description of the category.
meta_robots	string	No	INDEX,FOLLOW	The meta robots values of the category.
og_description	string	No	`description`	The open graph meta description of the category.
og_image_url	string	No		The URL to the open graph meta image of the category.
og_title	string	No	`title`	The open graph title of the category.
page_title	string	No	`title`	The HTML page title of the category.
slug	string	No	`title`	The slug of the category.
title	string	No		The title of the category.

Example Request

curl -i -X POST https://api.groovehq.com/v1/kb/4216430596/categories \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "title": "Uncategorized"
    }'

Example Response

Status: 201 Created

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": null,
        "slug": "uncategorized",
        "state": "draft",
        "title": "Uncategorized",
        "updated_at": "2019-10-31T08:48:00Z"
    }
}

Searching categories

GET https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/search

Parameters

Name	Type	Required	Default	Notes
keyword	string	Yes		The keyword to search the categories by. Use "*" for all.
author_id	string	No		The author ID to filter search results by.
order	string	No		The sortable field name and direction (asc ascending or desc descending) to order search results by.
page	intger	No	1	The page number of the search results.
per_page	integer	No	25	The number of search results per page.
state	string	No		The category state to filter search results by.
unpaginated	boolean	No	false	Whether to return unpaginated search results. Maximum number of results is 100.

Category states

A category can be in one of the following states:

draft - Created category, not published.
published - Published category, visible to end-users.
wip - New version being edited, while current version is published.

Sortable fields

Category search results can be ordered by one of the following fields:

articles_count - Order by number of articles.
position - Order by position.
title - Order by title.
updated_at - Order by last updated timestamp.

Example Request

curl -i -X GET https://api.groovehq.com/v1/kb/4216430596/categories/search?keyword=* \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "categories": [
        {
            "id": "5249150327",
            "articles_count": 0,
            "article_ids": [],
            "author_id": "0412191130",
            "cover_image_url": null,
            "created_at": "2019-10-31T08:48:00Z",
            "description": null,
            "featured": false,
            "knowledge_base_id": "4216430596",
            "meta_description": null,
            "meta_robots": "INDEX,FOLLOW",
            "og_description": null,
            "og_image_url": null,
            "og_title": null,
            "page_title": null,
            "position": 1,
            "published_at": null,
            "slug": "uncategorized",
            "state": "draft",
            "title": "Uncategorized",
            "updated_at": "2019-10-31T08:48:00Z"
        }
    ],
    "meta": {
        "pagination": {
            "current_page": 0,
            "total_pages": 1,
            "total_count": 1
        }
    }
}

Repositioning categories

PUT https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/reposition

Parameters

Name	Type	Required	Default	Notes
ids	array	Yes		The array of category IDs ordered by position.

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/categories/reposition \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d 'ids[]=1723475590&ids[]=5249150327'

Example Response

Status: 200 OK

{
    "categories": [
        {
            "id": "1723475590",
            "position": 1
        },
        {
            "id": "5249150327",
            "position": 2
        }
    ]
}

Getting categories counts

GET https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/counts

Parameters

Name	Type	Required	Default	Notes
keyword	string	Yes		The keyword to search the categories by. Use "*" for all.
groups	string	No		The comma separated list of group count fields.

Group counts fields

state - Number of categories groupped by state.

Example Request

curl -i -X GET https://api.groovehq.com/v1/kb/4216430596/categories/counts?keyword=*&groups=state \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "total_count": 2,
    "counts": {
        "state": {
            "draft": 1,
            "published": 1
        }
    }
}

Getting a category

GET https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id

Example Request

curl -i -X GET https://api.groovehq.com/v1/kb/4216430596/categories/5249150327 \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": null,
        "slug": "uncategorized",
        "state": "draft",
        "title": "Uncategorized",
        "updated_at": "2019-10-31T08:48:00Z"
    }
}

Updating a category

PUT https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id

Parameters

Name	Type	Required	Default	Notes
article_ids	array	No		The array of category IDs to associate with this category.
author_id	string	No	OAuth user	The ID of the user set as the author of the category.
description	string	No		The description of the category.
meta_description	string	No	`description`	The meta tag description of the category.
meta_robots	string	No	INDEX,FOLLOW	The meta robots values of the category.
og_description	string	No	`description`	The open graph meta description of the category.
og_image_url	string	No		The URL to the open graph meta image of the category.
og_title	string	No	`title`	The open graph title of the category.
page_title	string	No	`title`	The HTML page title of the category.
slug	string	No	`title`	The slug of the category.
title	string	No		The title of the category.

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/categories/5249150327 \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "title": "Default category",
        "slug": "default-category"
    }'

Example Response

Status: 200 OK

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": null,
        "slug": "default-category",
        "state": "draft",
        "title": "Default category",
        "updated_at": "2019-10-31T08:48:00Z"
    }
}

Publishing a category

PUT https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id/publish

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/categories/5249150327/publish \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": "2019-10-31T09:10:29+00:00",
        "slug": "default-category",
        "state": "published",
        "title": "Default category",
        "updated_at": "2019-10-31T09:10:29Z"
    }
}

Unpublishing a category

PUT https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id/unpublish

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/categories/5249150327/unpublish \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": null,
        "slug": "default-category",
        "state": "draft",
        "title": "Default category",
        "updated_at": "2019-10-31T09:10:29Z"
    }
}

Reverting a category

PUT https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id/revert

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/categories/5249150327/revert \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "category": {
        "id": "5249150327",
        "articles_count": 0,
        "article_ids": [],
        "author_id": "0412191130",
        "cover_image_url": null,
        "created_at": "2019-10-31T08:48:00Z",
        "description": null,
        "featured": false,
        "knowledge_base_id": "4216430596",
        "meta_description": null,
        "meta_robots": "INDEX,FOLLOW",
        "og_description": null,
        "og_image_url": null,
        "og_title": null,
        "page_title": null,
        "position": 1,
        "published_at": "2019-10-31T09:25:20Z",
        "slug": "default-category",
        "state": "published",
        "title": "Default category 2",
        "updated_at": "2019-10-31T09:25:25Z"
    }
}

Deleting a category

DELETE https://api.groovehq.com/v1/kb/:knowledge_base_id/categories/:id

Example Request

curl -i -X DELETE https://api.groovehq.com/v1/kb/4216430596/categories/5249150327 \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 204 No Content