Articles

View as Markdown

Articles are the pages of your help center. The API can read them, search the published ones and create drafts. A person publishes a draft in Tirver. If the workspace has switched the help center off, these endpoints answer 404 with module_disabled.

The article object

Field	Type	Meaning
`id`	string	The article id.
`slug`	string	The address-friendly name.
`title`	string	The title.
`status`	string	`draft` or `published`.
`collection`	object or null	The collection it is filed under, with `id`, `slug` and `name`.
`description`	string	The search description, or the start of the body.
`helpful_count`	integer	Readers who rated it helpful.
`not_helpful_count`	integer	Readers who rated it not helpful.
`published_at`	string or null	When it was first published.
`created_at`	string	When it was created.
`updated_at`	string	When it last changed.

Lists do not include the text. Fetching a single article adds body, the article text as Markdown.

List articles

GET/api/v1/help-center/articles

Needs the help-center:read scope. Drafts are included. Ordered by last update, newest first.

Parameter	Type	What it does
`status`	string	`draft` or `published`.
`collection_id`	string	Only articles in this collection.
`q`	string	Search the title and body.
`limit`	integer	Page size, 1 to 100. Defaults to 25.
`cursor`	string	The `next_cursor` from the previous page.

curl "https://app.tirver.com/api/v1/help-center/articles?status=published&q=widget" \
  -H "Authorization: Bearer $TIRVER_API_KEY"

Get an article

GET/api/v1/help-center/articles/{id}

Needs help-center:read. {id} is the article id or its slug. Returns one article with its Markdown body.

Search published articles

GET/api/v1/search

Needs help-center:read. A keyword search over published articles. It matches words, not meaning, and titles rank first. For a natural language answer, use POST /api/v1/ask.

Parameter	Type	What it does
`q`	string	Required. The words to look for.
`limit`	integer	How many results, 1 to 50. Defaults to 10.

List collections

GET/api/v1/help-center/collections

Needs help-center:read. Returns every collection, not paged, each with id, slug, name, article_count and published_article_count.

Create an article draft

POST/api/v1/help-center/articles

Needs help-center:write. The article is always created as a draft, so nothing is shown to customers until a person publishes it. Returns 201 with the article. A slug that is already taken gives 409.

Field	Type	What it does
`title`	string	Required. Up to 160 characters.
`body`	string	The text, as Markdown.
`collection_id`	string	Optional. The collection to file it under.
`slug`	string	Optional. Lowercase letters, numbers and dashes. Made from the title when left out.
`description`	string	Optional. The search description, up to 320 characters.

curl

curl https://app.tirver.com/api/v1/help-center/articles \
  -H "Authorization: Bearer $TIRVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Reset your password", "body": "Open Settings, then Profile."}'

JavaScript

const res = await fetch('https://app.tirver.com/api/v1/help-center/articles', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TIRVER_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Reset your password', body: 'Open Settings, then Profile.' }),
});
const article = await res.json();

Python

res = requests.post(
    "https://app.tirver.com/api/v1/help-center/articles",
    headers={"Authorization": f"Bearer {os.environ['TIRVER_API_KEY']}"},
    json={"title": "Reset your password", "body": "Open Settings, then Profile."},
    timeout=10,
)
article = res.json()

The response has the article fields above plus body, with status set to draft and collection set to null when you gave no collection.