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

# Article & cluster fields

> RankBuddy SDK data shapes for blog pages — every field your frontend should support.

Use these fields when building listing cards, article pages, topic hubs, and metadata.

## `RankBuddyArticle`

| Field              | Type                                                    | Use on your site                                    |
| ------------------ | ------------------------------------------------------- | --------------------------------------------------- |
| `id`               | `string`                                                | Keys, analytics (optional on public pages)          |
| `slug`             | `string`                                                | URL segment at `{blogPath}/[slug]`                  |
| `title`            | `string`                                                | `<h1>`, cards, Open Graph fallback                  |
| `description`      | `string`                                                | Meta description fallback, card excerpt             |
| `excerpt`          | `string?`                                               | Prefer over `description` for card blurbs           |
| `content`          | `{ format: "markdown"; html: string; source?: string }` | Render `content.html` in article body               |
| `coverImage`       | `string?`                                               | Hero image, OG/Twitter image fallback               |
| `publishedAt`      | `string?`                                               | Byline, JSON-LD `datePublished`, OG `publishedTime` |
| `updatedAt`        | `string?`                                               | JSON-LD `dateModified`, OG `modifiedTime`           |
| `readingTime`      | `number?`                                               | Minutes to read (round up, minimum 1)               |
| `tags`             | `string[]?`                                             | Topic chips on the article page                     |
| `clusterRelation`  | `"pillar" \| "supporting"?`                             | Optional badge (pillar vs supporting)               |
| `primaryKeyword`   | `string?`                                               | Optional chip or metadata                           |
| `primaryCluster`   | `{ id, slug, name, pillarKeyword }?`                    | Link to `{blogPath}/topic/{slug}`                   |
| `seo.title`        | `string?`                                               | `<title>` and OG title                              |
| `seo.description`  | `string?`                                               | Meta description                                    |
| `seo.canonicalUrl` | `string?`                                               | Canonical link (absolute or site-relative)          |
| `seo.ogImage`      | `string?`                                               | Prefer over `coverImage` for social cards           |
| `seo.keywords`     | `string[]?`                                             | Meta keywords, JSON-LD `keywords`                   |
| `seo.noIndex`      | `boolean?`                                              | Set `robots: { index: false, follow: false }`       |

## `RankBuddyCluster`

| Field                     | Type       | Use on your site                        |
| ------------------------- | ---------- | --------------------------------------- |
| `slug`                    | `string`   | URL at `{blogPath}/topic/[clusterSlug]` |
| `name`                    | `string`   | Topic page `<h1>`                       |
| `pillarKeyword`           | `string`   | Subtitle, meta keywords                 |
| `notes`                   | `string?`  | Topic page description                  |
| `postCount`               | `number`   | Optional stat                           |
| `keywords`                | `string[]` | Meta keywords                           |
| `createdAt` / `updatedAt` | `string?`  | Sitemap `lastmod`                       |

## Client options (`createRankBuddyClient`)

| Option         | Required    | Purpose                                                  |
| -------------- | ----------- | -------------------------------------------------------- |
| `apiKey`       | Yes         | Server-only secret (`RANKBUDDY_API_KEY`)                 |
| `siteUrl`      | Recommended | Builds canonical URLs when `seo.canonicalUrl` is missing |
| `blogPath`     | Recommended | Must match your project's content path (e.g. `/blog`)    |
| `apiUrl`       | No          | Custom API base (HTTPS only)                             |
| `timeoutMs`    | No          | Default `10000`                                          |
| `allowBrowser` | No          | Keep `false` for secret keys                             |

## SDK list parameters

**`getArticlesList(client, params)`**

| Param   | Type      | Default behavior                  |
| ------- | --------- | --------------------------------- |
| `limit` | `number?` | Page size (index often uses `24`) |
| `page`  | `number?` | 1-based pagination                |
| `tag`   | `string?` | Filter by tag when needed         |

**`getClusterArticles(client, clusterSlug, params)`**

| Param   | Type      | Default behavior |
| ------- | --------- | ---------------- |
| `limit` | `number?` | Topic grid size  |
| `page`  | `number?` | Pagination       |