Knowledge base

Help centre categories and articles.

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/categories

limit

integer · min: 1 · max: 100

Rows per page.

Default: 25

cursor

string

The next_cursor of the previous page.

List categories

KbCategory[] · required

next_cursor

string · required

Pass back as cursor for the next page. Null on the last page.

List articles

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles

List articles › query Parameters

limit

integer · min: 1 · max: 100

Rows per page.

Default: 25

cursor

string

The next_cursor of the previous page.

status

string · enum

Enum values:

draft

published

category_id

string · uuid

List articles › Responses

List articles

KbArticle[] · required

next_cursor

string · required

Pass back as cursor for the next page. Null on the last page.

GET/kb/articles

curl 'https://{workspace}.open-helpdesk.com/api/v1/kb/articles' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
      "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
      "title": "Exporting your invoices",
      "slug": "exporting-your-invoices",
      "body_html": "<p>Open <strong>Billing</strong>, then…</p>",
      "status": "draft",
      "author_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
      "published_at": "2024-08-25T15:00:00Z",
      "view_count": 0,
      "votes_up": 0,
      "votes_down": 0,
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "next_cursor": "next_cursor"
}

json

application/json

Create an article

POST

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles

Lands as a draft unless status says otherwise: publishing puts text in front of customers.

Create an article › Request Body

title

string · maxLength: 300 · required

category_id

string · uuid · required

body_html

string

slug

string

Derived from the title when omitted.

status

string · enum

Enum values:

draft

published

Default: draft

Create an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

POST/kb/articles

curl 'https://{workspace}.open-helpdesk.com/api/v1/kb/articles' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "title": "Exporting your invoices",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "body_html": "<p>Open <strong>Billing</strong>, then…</p>",
  "slug": "slug",
  "status": "draft"
}'

Example Request Body

{
  "title": "Exporting your invoices",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "body_html": "<p>Open <strong>Billing</strong>, then…</p>",
  "slug": "slug",
  "status": "draft"
}

json

Example Responses

{
  "id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "title": "Exporting your invoices",
  "slug": "exporting-your-invoices",
  "body_html": "<p>Open <strong>Billing</strong>, then…</p>",
  "status": "draft",
  "author_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "published_at": "2024-08-25T15:00:00Z",
  "view_count": 0,
  "votes_up": 0,
  "votes_down": 0,
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Read an article

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles/{id}

Read an article › path Parameters

id

string · uuid · required

The article id.

Example: 3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83

Read an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

Delete an article

DELETE

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles/{id}

Delete an article › path Parameters

id

string · uuid · required

The article id.

Example: 3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83

Delete an article › Responses

Deleted.

No data returned

Update an article

PATCH

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles/{id}

published_at is stamped on the first publication only — a re-publish never rewrites it.

Update an article › path Parameters

id

string · uuid · required

The article id.

Example: 3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83

Update an article › Request Body

title

string

body_html

string

category_id

string · uuid

slug

string

status

string · enum

Enum values:

draft

published

Update an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

PATCH/kb/articles/{id}

curl 'https://{workspace}.open-helpdesk.com/api/v1/kb/articles/:id' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "title": "title",
  "body_html": "body_html",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "slug": "slug",
  "status": "draft"
}'

Example Request Body

{
  "title": "title",
  "body_html": "body_html",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "slug": "slug",
  "status": "draft"
}

json

Example Responses

{
  "id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "category_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "title": "Exporting your invoices",
  "slug": "exporting-your-invoices",
  "body_html": "<p>Open <strong>Billing</strong>, then…</p>",
  "status": "draft",
  "author_id": "3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83",
  "published_at": "2024-08-25T15:00:00Z",
  "view_count": 0,
  "votes_up": 0,
  "votes_down": 0,
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Organizations Attachments

List categories

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/categories

limit

integer · min: 1 · max: 100

Rows per page.

Default: 25

cursor

string

The next_cursor of the previous page.

List categories

KbCategory[] · required

next_cursor

string · required

Pass back as cursor for the next page. Null on the last page.

List articles

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles

List articles › query Parameters

limit

integer · min: 1 · max: 100

Rows per page.

Default: 25

cursor

string

The next_cursor of the previous page.

status

string · enum

Enum values:

draft

published

category_id

string · uuid

List articles › Responses

List articles

KbArticle[] · required

next_cursor

string · required

Pass back as cursor for the next page. Null on the last page.

Create an article

POST

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles

Lands as a draft unless status says otherwise: publishing puts text in front of customers.

Create an article › Request Body

title

string · maxLength: 300 · required

category_id

string · uuid · required

body_html

string

slug

string

Derived from the title when omitted.

status

string · enum

Enum values:

draft

published

Default: draft

Create an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

Read an article

GET

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles/{id}

Read an article › path Parameters

id

string · uuid · required

The article id.

Example: 3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83

Read an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

Update an article

PATCH

https://{workspace}.open-helpdesk.com/api/v1

/kb/articles/{id}

published_at is stamped on the first publication only — a re-publish never rewrites it.

Update an article › path Parameters

id

string · uuid · required

The article id.

Example: 3f2a1c94-8e5b-4d17-9f60-2c7b1a0d5e83

Update an article › Request Body

title

string

body_html

string

category_id

string · uuid

slug

string

status

string · enum

Enum values:

draft

published

Update an article › Responses

Success.

KbArticle

id

string · uuid

category_id

string · uuid

title

string

slug

string

body_html

string

status

string · enum

Enum values:

draft

published

author_id

string · uuid

published_at

string · date-time

view_count

integer

votes_up

integer

votes_down

integer

created_at

string · date-time

updated_at

string · date-time

Knowledge base

List categories

List categories › query Parameters

List categories › Responses

List articles

List articles › query Parameters

List articles › Responses

Create an article

Create an article › Request Body

Create an article › Responses

Read an article

Read an article › path Parameters

Read an article › Responses

Delete an article

Delete an article › path Parameters

Delete an article › Responses

Update an article

Update an article › path Parameters

Update an article › Request Body

Update an article › Responses

Knowledge base

List categories

List categories › query Parameters

List categories › Responses

List articles

List articles › query Parameters

List articles › Responses

Create an article

Create an article › Request Body

Create an article › Responses

Read an article

Read an article › path Parameters

Read an article › Responses

Delete an article

Delete an article › path Parameters

Delete an article › Responses

Update an article

Update an article › path Parameters

Update an article › Request Body

Update an article › Responses