Skip to main content
GET
List articles

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

portalSlug
string
required

The portal's slug — the URL-safe handle you see in its public address (/hc/<slug>/...), not a numeric id. List portals returns every slug on the account. Note the asymmetry: portals are addressed by slug, articles by numeric id.

Example:

"acme-help"

Query Parameters

locale
string

Keep only articles of this locale.

Example:

"en"

status
enum<string>

Keep only articles in this status.

Available options:
draft,
published,
archived
category_slug
string

Keep only articles filed under this category, addressed by the category's slug. Prefer category_id when you have it: a slug can be rewritten by updating the category, and a filter holding an old slug matches nothing and reports no error.

Example:

"getting-started"

category_id
integer

Keep only articles filed under this category, addressed by its numeric id. List categories returns the ids, and every article carries its own in category_id. The stable way to name a category: unlike the slug, the id never changes. An id that is not in this portal is not an error — the page just comes back empty. Sent together with category_slug, both narrow, so an article has to match the two. A value that is not a positive integer is a 400 naming category_id.

Example:

12

query
string

Full-text search over title, description and content. Matches word prefixes: pass finds “password”.

Example:

"password"

page
integer
default:1

1-based page number. Anything below 1 — including a non-numeric value — is read as 1.

Required range: x >= 1
Example:

1

per_page
integer
default:25

Results per page. Clamped, never rejected: above 100 you get 100, below 1 you get the default 25.

Required range: 1 <= x <= 100
Example:

25

Response

A page of articles. data is empty when nothing matches — an empty page is not a 404.

One page of articles.

data
object[]
required
meta
object
required

Where you are in the result set.