API
Login Sign Up

Knowlede base Articles

Creating an article

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

Parameters

Name Type Required Default Notes
author_id string No OAuth user The ID of the user set as the author of the article.
body string No The body of the article. This may include HTML formatting.
category_id integer No The ID of the category for this article.
description string No The description of the article.
featured boolean No false Whether the article is featured.
meta_description string No description The meta tag description of the article.
meta_robots string No INDEX,FOLLOW The meta robots values of the article.
og_description string No description The open graph meta description of the article.
og_image_url string No The URL to the open graph meta image of the article.
og_title string No title The open graph title of the article.
page_title string No title The HTML page title of the article.
related_ids array No The array of other article IDs of this knowledge base to associate with this article.
slug string No title The slug of the article.
tags array No The array of tag names for the article. Nonexistent tags will be automatically created.
title string No The title of the article.

Example Request

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

Example Response

Status: 201 Created

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": null,
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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,
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "draft",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:36:44Z",
        "updater_id": "0412191130"
    }
}

Searching articles

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

Parameters

Name Type Required Default Notes
keyword string Yes The keyword to search the articles by. Use "*" for all.
author_id string No The author ID to filter search results by.
category_id string No The category ID to filter search results by.
featured boolean No Whether to filter search results by featured articles only.
ids array No The array of article IDs 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 article state to filter search results by.
tag string No The tag name to filter search results by.
unpaginated boolean No false Whether to return unpaginated search results. Maximum number of results is 100.

Article states

An article can be in one of the following states:

  • draft - Created article, not published.
  • published - Published article, visible to end-users.
  • wip - New version being edited, while current version is published.
  • deleted - Article soft deleted.

Sortable fields

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

  • average_ratings - Order by average articles ratings.
  • 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/articles/search?keyword=* \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json"

Example Response

Status: 200 OK

{
    "articles": [
        {
            "id": "0759213294",
            "author_id": "0412191130",
            "body": null,
            "category_id": null,
            "created_at": "2019-10-31T09:36:44Z",
            "deleted_at": null,
            "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:38:03Z",
            "ratings": {},
            "related_ids": [],
            "slug": "getting-started",
            "state": "published",
            "title": "Getting started",
            "updated_at": "2019-10-31T09:38:03Z",
            "updater_id": "0412191130"
        }
    ],
    "meta": {
        "pagination": {
            "current_page": 0,
            "total_pages": 1,
            "total_count": 1
        }
    }
}

Repositioning articles

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

Parameters

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

Example Request

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

Example Response

Status: 200 OK

{
    "articles": [
        {
            "id": "9422013947",
            "position": 1
        },
        {
            "id": "3219430297",
            "position": 2
        }
    ]
}

Getting articles counts

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

Parameters

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

Group counts fields

  • state - Number of articles groupped by state.
  • tag - Number of articles groupped by tag.

Example Request

curl -i -X GET https://api.groovehq.com/v1/kb/4216430596/articles/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 articles tags

GET https://api.groovehq.com/v1/kb/:knowledge_base_id/articles/tags

Example Request

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

Example Response

Status: 200 OK

{
  "tags": [
      {
          "id": "9452013746",
          "created_at": "2019-08-20T13:47:24Z",
          "name": "Ruby",
          "taggings_count": 2,
          "updated_at": "2019-08-20T13:47:24Z"
      },
      {
          "id": "6149150327",
          "created_at": "2019-10-31T09:47:58Z",
          "name": "how-to",
          "taggings_count": 1,
          "updated_at": "2019-10-31T09:47:58Z"
      },
      {
          "id": "1623475690",
          "created_at": "2019-10-31T09:47:58Z",
          "name": "space",
          "taggings_count": 1,
          "updated_at": "2019-10-31T09:47:58Z"
      }
  ]

}

Getting an article

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": null,
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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:38:03Z",
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "published",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:38:03Z",
        "updater_id": "0412191130"
    }
}

Updating an article

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

Parameters

Name Type Required Default Notes
author_id string No OAuth user The ID of the user set as the author of the article.
body string No The body of the article. This may include HTML formatting.
category_id integer No The ID of the category for this article.
description string No The description of the article.
featured boolean No false Whether the article is featured.
meta_description string No description The meta tag description of the article.
meta_robots string No INDEX,FOLLOW The meta robots values of the article.
og_description string No description The open graph meta description of the article.
og_image_url string No The URL to the open graph meta image of the article.
og_title string No title The open graph title of the article.
page_title string No title The HTML page title of the article.
related_ids array No The array of other article IDs of this knowledge base to associate with this article.
slug string No title The slug of the article.
tags array No The array of tag names for the article. Nonexistent tags will be automatically created.
title string No The title of the article.

Example Request

curl -i -X PUT https://api.groovehq.com/v1/kb/4216430596/articles/0759213294 \
    -H "Authorization: Bearer $GROOVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "title": "Getting started with Moon",
        "categoryId": "5249150327"
    }'

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": "5249150327",
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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:38:03Z",
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "wip",
        "tags": [],
        "title": "Getting started with Moon",
        "updated_at": "2019-10-31T09:43:47Z",
        "updater_id": "0412191130"
    }
}

Publishing an article

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": null,
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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:38:03+00:00",
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "published",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:38:03Z",
        "updater_id": "0412191130"
    }
}

Unpublishing an article

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": "5249150327",
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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,
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "draft",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:44:45Z",
        "updater_id": "0412191130"
    }
}

Reverting an article

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": "5249150327",
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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:45:26Z",
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "published",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:45:26Z",
        "updater_id": "0412191130"
    }
}

Deleting an article (soft)

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": "5249150327",
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": "2019-10-31T09:51:33Z",
        "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:48:40Z",
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "deleted",
        "tags": [
            "space",
            "how-to"
        ],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:51:33Z",
        "updater_id": "0412191130"
    }
}

Restoring an article (from soft deletion)

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

Example Request

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

Example Response

Status: 200 OK

{
    "article": {
        "id": "0759213294",
        "author_id": "0412191130",
        "body": null,
        "category_id": "5249150327",
        "created_at": "2019-10-31T09:36:44Z",
        "deleted_at": null,
        "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,
        "ratings": {},
        "related_ids": [],
        "slug": "getting-started",
        "state": "draft",
        "tags": [],
        "title": "Getting started",
        "updated_at": "2019-10-31T09:56:26Z",
        "updater_id": "0412191130"
    }
}

Permanently deleting an article

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

Example Request

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

Example Response

Status: 204 No Content