# Articles

> Read help center articles, search them and create drafts.

Articles are the pages of your [help center](https://tirver.com/help/write-your-first-article.md). 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. |

```bash
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**

```bash
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**

```js
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**

```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.

Source: https://tirver.com/help/api/articles