Categories

How to list docs-categories

Request Overview

Actions	Returns	Description
`GET` /api/v1/docs/categories	`Collection`	Get all categories
`POST` /api/v1/docs/categories	`Object`	Create category
`PATCH` /api/v1/docs/categories/{id}	`Object`	Update category
`DELETE` /api/v1/docs/categories/{id}		Delete category

Fields

Category Object

Field	Type	Required	Specifics
`name`	`String`	yes
`description`	`String`
`docs_site_id`	`Integer 0\|1`		ID of the related docs-site
`locale_default`	`String`		The default locale of the category.
`locales_enabled`	`Array`		Array of locales that are available in public
`locale_default`
`localized`			Localized content
`localized.name.*`	`String`
`localized.description.*`	`String`

`created_at`	`Date` `String`
`updated_at`	`Date` `String`
`last_modified_at`	`Date` `String`		Last change date of the site, its categories or articles.

Requests

Get All Categories

GET /api/v1/docs/categories Returns, a collection of category

GET /api/v1/docs/categories HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": [
    {
      "id": 1,
      "docs_site_id": 1,
      "name": "Create new tickets",
      "description": "How to create new tickets",
      "locale_default": "en",
      "localized": [
        {
          "name": {
            "de-DE": "Neue Tickets erstellen",
            "en": "Create new tickets",
            "fr": "Créer de nouveaux tickets"
          }
        },
        {
          "description": {
            "de-DE": "Wie man neue Tickets erstellt",
            "en": "How to create new tickets",
            "fr": "Comment créer de nouveaux tickets"
          }
        }
      ],
      "created_at": "2023-05-31T14:12:10+00:00",
      "updated_at": "2024-07-18T13:28:52+00:00"
    },
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    ...
  }
}

Information about links and meta, please read this article.

Create Category

POST /api/v1/docs/categories Create a category

POST /api/v1/docs/categories HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

{
  "docs_site_id": 1,
  "name": "New category",
  "description": "Optional description"
}

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "docs_site_id": 1,
  "name": "New category via API",
  "description": "Optional description"
}

Update Category

PATCH /api/v1/docs/categories/{id} Update a category

PATCH /api/v1/docs/categories/12 HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

{
  "name": "Updated category name",
  "description": "Updated description"
}

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "name": "Updated category name",
  "description": "Updated description"
}

Delete Category

DELETE /api/v1/docs/categories/{id} Delete a category

DELETE /api/v1/docs/categories/12 HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json