# Articles API

> Serve published knowledge base articles to help centers, portals, and third-party apps.

URL: https://docs.reaktly.com/docs/api-reference/articles

## Overview

The Articles API exposes **published, public** articles from a knowledge base as JSON — for help centre widgets, customer portals, and integrations that render their own front end.

- **Base URL:** `https://api.reaktly.com`
- **Scope:** `articles:read` (see [Authentication](/docs/api-reference/authentication))
- Only articles with publish status `PUBLISHED` and visibility `PUBLIC` are returned.
- `kbId` is the knowledge base's UUID.

```bash
curl "https://api.reaktly.com/public/knowledge-bases/kb_xyz789/articles?page=1&pageSize=20" \
  -H "x-api-key: YOUR_API_KEY"
```

## Articles

### `GET /public/knowledge-bases/{kbId}/articles`

Paginated list of published articles.

| Query parameter | Type | Description |
|---|---|---|
| `channel` | string | Filter by delivery channel: `ALL`, `HELP_CENTER`, `WIDGET`, `PARTNER_PORTAL`, `INTERNAL`, `API` |
| `categorySlug` / `categoryId` | string | Restrict to one category |
| `featured` | boolean | Only featured articles |
| `search` | string | Keyword search over title, excerpt and body |
| `page` | number | 1-based page number (default `1`) |
| `pageSize` | number | Articles per page (default `20`, max `100`) |

```json
{
  "articles": [
    {
      "id": "pub_123",
      "slug": "how-to-reset-your-password",
      "title": "How to reset your password",
      "contentType": "ARTICLE",
      "excerpt": "Reset your password from the sign-in screen…",
      "body": "Full article text…",
      "imageUrl": "https://cdn.example.com/cover.png",
      "category": { "id": "cat_1", "name": "Account", "slug": "account" },
      "entryPoints": [
        { "id": "ep_1", "question": "I forgot my password", "snippet": "Use the reset link…", "isPrimary": true, "tags": ["login"] }
      ],
      "readingTimeMinutes": 3,
      "publishedAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-09-10T12:30:00.000Z",
      "helpfulness": { "helpfulCount": 42, "notHelpfulCount": 3 }
    }
  ],
  "total": 128,
  "page": 1,
  "pageSize": 20,
  "totalPages": 7
}
```

### `GET /public/knowledge-bases/{kbId}/articles/by-slug/{slug}`

A single article by its URL slug. Also increments the article's view count. Returns `404` when the article is not published or not public.

### `GET /public/knowledge-bases/{kbId}/articles/{publicationId}`

A single article by its publication ID. Also increments the view count.

### `POST /public/knowledge-bases/{kbId}/articles/{publicationId}/feedback`

Record whether a reader found the article helpful.

```json
{ "isHelpful": true }
```

Response `200`:

```json
{ "helpfulCount": 43, "notHelpfulCount": 3 }
```

## Categories

### `GET /public/knowledge-bases/{kbId}/articles/categories`

The category tree for navigation, with published article counts and nested children.

```json
[
  {
    "id": "cat_1",
    "name": "Account",
    "slug": "account",
    "description": null,
    "icon": null,
    "articleCount": 12,
    "children": []
  }
]
```

## Questions

Entry-point questions are the fastest discovery path — visitors search a question and jump to the article that answers it.

### `GET /public/knowledge-bases/{kbId}/articles/questions/search`

| Query parameter | Type | Description |
|---|---|---|
| `q` | string | Search text, e.g. `how do I reset my password` |
| `limit` | number | Max results (default `10`, max `50`) |
| `channel` | string | Filter by delivery channel |
| `categorySlug` | string | Restrict to one category |

Returns matching questions with their snippets.

### `GET /public/knowledge-bases/{kbId}/articles/questions/popular`

Popular questions ranked by how often they are matched — useful for a help centre landing page or the widget's initial state. Takes the same `limit`, `channel` and `categorySlug` parameters.

### Question analytics

Two endpoints feed the "popular questions" ranking. Both return `204 No Content`:

| Endpoint | Call it when |
|---|---|
| `POST /public/knowledge-bases/{kbId}/articles/questions/{entryPointId}/matched` | The question appeared in your search results |
| `POST /public/knowledge-bases/{kbId}/articles/questions/{entryPointId}/clicked` | A visitor clicked through to the article (also increments the article's view count) |

## Errors

| Status | Meaning |
|---|---|
| `401` | Missing or invalid API key |
| `403` | Key lacks `articles:read` |
| `404` | Article not found, or not published and public |