> For the complete Lynkow documentation index in agent-friendly format, see [llms.txt](/llms.txt).

# CategoriesService

**Publié le** : 2026-08-20
**Catégorie** : Services

# CategoriesService

Service for retrieving content categories and their hierarchical structure.

Accessible via `lynkow.categories`. Categories organize blog articles and can be
nested (parent/child). Each category includes a content count and optional image.
Responses are cached for 5 minutes (SHORT TTL) when a cache adapter is configured.

Access via: `lynkow.categories`

## Methods

**4** methods

### `clearCache`

```typescript
clearCache(): void
```

Invalidate every cached category response (flat list, hierarchy
tree, detail views with paginated contents). Call after an admin
mutation or on receipt of a `category.*` webhook so the next public
request bypasses the 30-minute SWR cache.

Returns: `void`

```typescript
// On category restructuring:
lynkow.categories.clearCache()
```

---

### `getBySlug`

```typescript
getBySlug(slug: string, options?: CategoryOptions & BaseRequestOptions): Promise<CategoryDetailResponse>
```

Retrieves a single category by its slug, along with a paginated list of
the published articles that belong to it. Cached for 5 minutes per
slug+locale+pagination combination.

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | `string` | The unique URL slug of the category (e.g. `'tech'`, `'news'`, `'tutorials'`) |
| `options` | `CategoryOptions & BaseRequestOptions` | Combined category and request options:<br>  - `page` / `limit` — pagination for the category's articles (defaults to page 1)<br>  - `locale` — override the client's default locale |


Returns: `Promise<CategoryDetailResponse>`

```typescript
const { category, contents } = await lynkow.categories.getBySlug('tech', {
  page: 1,
  limit: 10
})
console.log(category.name)             // "Tech"
console.log(contents.data.length)      // Number of articles on this page
console.log(contents.meta.hasMorePages) // Whether more pages exist
```

---

### `list`

```typescript
list(options?: BaseRequestOptions): Promise<CategoriesListResponse>
```

Retrieves a flat list of all categories with their content counts.
Useful for building navigation menus, sidebars, or category filters.
Cached for 5 minutes per locale.

| Parameter | Type | Description |
| --- | --- | --- |
| `options` | `BaseRequestOptions` | Request options; use `locale` to fetch localized category names |


Returns: `Promise<CategoriesListResponse>`

```typescript
const { categories, blogUrlMode } = await lynkow.categories.list()
categories.forEach(cat => {
  console.log(`${cat.name} (${cat.contentCount} articles)`)
})
```

---

### `tree`

```typescript
tree(options?: BaseRequestOptions): Promise<CategoryTreeResponse>
```

Retrieves the full category hierarchy as a nested tree structure.
Root categories appear at the top level, each with a `children` array
containing their subcategories (recursively). Useful for building
hierarchical navigation or breadcrumbs. Cached for 5 minutes per locale.

| Parameter | Type | Description |
| --- | --- | --- |
| `options` | `BaseRequestOptions` | Request options; use `locale` to fetch localized category names |


Returns: `Promise<CategoryTreeResponse>`

```typescript
const { tree } = await lynkow.categories.tree()
// Iterate root categories and their children
tree.forEach(root => {
  console.log(root.name)
  root.children.forEach(child => {
    console.log(`  - ${child.name}`)
  })
})
```