> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Learn

> Access Learn Hub articles and track per-user reading progress for in-product education.

The Learn Hub provides curated articles to help users get the most out of HelpGenie. Progress is tracked per user — viewing an article automatically updates `last_viewed_at`, and users can explicitly mark articles complete or incomplete.

Only published articles are returned.

***

## Actions

### `all` / `list`

Returns a paginated list of published articles with the current user's progress joined.

**Parameters**

| Field                | Type    | Required | Description                           |
| -------------------- | ------- | -------- | ------------------------------------- |
| `limit`              | number  | No       | Max results, default `100`, max `500` |
| `offset`             | number  | No       | Pagination offset, default `0`        |
| `filters.startHere`  | boolean | No       | Only return "Start Here" articles     |
| `filters.category`   | string  | No       | Filter by category slug               |
| `filters.searchTerm` | string  | No       | Case-insensitive title search         |
| `startHere`          | boolean | No       | Shorthand for `filters.startHere`     |

**Response**

```json theme={null}
{
  "articles": [
    {
      "id": "article-uuid",
      "title": "Getting started with your first Genie",
      "slug": "getting-started-first-genie",
      "category": "setup",
      "is_start_here": true,
      "order_index": 1,
      "completed_at": null,
      "last_viewed_at": "2024-01-05T10:00:00Z"
    }
  ],
  "count": 24,
  "limit": 100,
  "offset": 0
}
```

***

### `get`

Returns a single published article by `slug` (preferred) or `id`. Automatically records `last_viewed_at` for the current user as a side effect.

**Parameters**

| Field  | Type   | Required    | Description                                   |
| ------ | ------ | ----------- | --------------------------------------------- |
| `slug` | string | Conditional | Article slug — preferred lookup key           |
| `id`   | string | Conditional | Article UUID — used if `slug` is not provided |

At least one of `slug` or `id` is required.

**Response**

```json theme={null}
{
  "article": {
    "id": "article-uuid",
    "title": "Getting started with your first Genie",
    "slug": "getting-started-first-genie",
    "category": "setup",
    "is_start_here": true,
    "order_index": 1,
    "body_markdown": "## Introduction\n\nWelcome to HelpGenie...",
    "completed_at": null,
    "last_viewed_at": "2024-01-07T10:00:00Z"
  }
}
```

***

### `progress`

Returns all progress records for the current user — one entry per article they have viewed or completed.

**Parameters** — none

**Response**

```json theme={null}
{
  "progress": [
    {
      "article_id": "article-uuid",
      "completed_at": "2024-01-06T09:00:00Z",
      "last_viewed_at": "2024-01-06T09:00:00Z"
    }
  ]
}
```

***

### `mark-complete`

Marks an article as completed for the current user. Sets both `completed_at` and `last_viewed_at` to now.

**Parameters**

| Field       | Type   | Required    | Description                                           |
| ----------- | ------ | ----------- | ----------------------------------------------------- |
| `id`        | string | Conditional | Article UUID (request ID)                             |
| `articleId` | string | Conditional | Article UUID (data field) — used if `id` not provided |

**Response**

```json theme={null}
{
  "success": true,
  "article_id": "article-uuid",
  "completed_at": "2024-01-07T10:00:00Z"
}
```

***

### `mark-incomplete`

Clears the `completed_at` timestamp for an article, marking it as not completed.

**Parameters**

| Field       | Type   | Required    | Description               |
| ----------- | ------ | ----------- | ------------------------- |
| `id`        | string | Conditional | Article UUID (request ID) |
| `articleId` | string | Conditional | Article UUID (data field) |

**Response**

```json theme={null}
{
  "success": true,
  "article_id": "article-uuid"
}
```

***

## Error codes

| Code               | Meaning                            |
| ------------------ | ---------------------------------- |
| `VALIDATION_ERROR` | Missing article ID or slug         |
| `NOT_FOUND`        | Article not found or not published |
| `INTERNAL_ERROR`   | Unexpected server error            |