# Knowledge base

> Manage knowledge-base collections and articles.

Product: Clad API
Source: https://docs.useclad.ai/api/knowledge-base

---

Manage collections (folders) and articles.

```graphql
query Kb {
  collections(first: 20) { edges { node { id name } } }
  articles(first: 20, status: published, search: "billing") {
    edges { node { id title slug status visibility } }
  }
  featuredArticles {
    id title position isAvailable unavailableReason
  }
  featuredArticleCandidates(search: "getting started", first: 20) {
    id title currentPosition
  }
}

mutation NewArticle($input: CreateArticleInput!) {
  createArticle(input: $input) {
    article { id title slug status }
    error { code message }
  }
}
```

Article `status` is `draft` or `published`; `visibility` is `public`,
`customer`, `internal`, or `ai_agent_only`. Reads need `articles:read`; writes
need `articles:write` (and `collections:write` to manage collections). Creating
or transitioning an article to `published` + `public` also requires the
`articles:publish` scope. This scope is member-eligible and is satisfied by
coarse `write`; an `articles:write`-only key still needs the explicit publish
scope.

Use `featuredArticles` to read the complete manually pinned help-center homepage
set. It includes retained pins that are temporarily unavailable, so clients can
preserve or reorder them rather than silently dropping them. Candidate search is
metadata-only and returns at most 50 published, public, listed articles from
included collections.

`replaceFeaturedArticles` atomically replaces the **entire** ordered pin set:

```graphql
mutation FeatureArticles($input: ReplaceFeaturedArticlesInput!) {
  replaceFeaturedArticles(input: $input) {
    featuredCount
    articleIds
    error { code message fields { path message } }
  }
}
```

Pass up to six unique Article ids. Omitted existing pins are unpinned; pass an
empty list to clear manual pins and restore automatic recency. The mutation
requires `articles:write` plus the same supplemental `articles:publish` grant as
other public-publication actions. New pins must be published, public, listed,
and belong to an included collection; already-pinned unavailable articles may
still be retained or reordered.