# Articles

> Articles are the building blocks of your Knowledge Base. Create, list, update, and delete the content your AI Agent uses to answer questions.

Articles are the building blocks of your AI Agent's Knowledge Base. Each article represents a piece of knowledge — a help page, FAQ entry, product description, or any content your AI should know about.

There are three article types: **Articles** (full documents with title and body), **Paragraphs** (short standalone text entries), and **URL articles** (automatically created when importing web content). You can create articles manually via the API, import them from websites using [Import External Content](/docs/api-reference/knowledge-base/import-external-content), upload files via [File Upload](/docs/api-reference/knowledge-base/file-upload), or sync from [Intercom](/docs/api-reference/knowledge-base/intercom-knowledge-base).

There is no retraining step. Every article you create, update, or delete is processed automatically in the background and takes effect as soon as it's done — usually within seconds. Track it with the `embed_state` field below, or with `pending_embed_count` in [Get Knowledge Base Settings](/docs/api-reference/knowledge-base#get-settings).

## Optional example checks

- [Preview an API Action request][public-lab-action-request-post]. Render a supplied request template with synthetic sample values without sending it. Omit credential headers.

- [Preview JSONPath matches][public-lab-action-response-post]. Check root, field, array-index and wildcard paths against supplied JSON. This does not run an Action or save conversation memory.

## Create Article

**Scope: write_all**

`POST https://app.quickchat.ai/v1/api/knowledge_base/articles/`

**Request Body**

| Parameter | Description |
|-----------|-------------|
| `content` <br/> string, required | Article content |
| `type` <br/> string | `"Article"` (default) or `"Paragraph"` |
| `title` <br/> string | Article title |

:::note[Article Types]
- **`"Article"`** — A full knowledge base document with title and content. Use for FAQ entries, help articles, product descriptions.
- **`"Paragraph"`** — A short standalone text entry without a title. Use for brief facts, one-liner answers, quick reference data.
- **`"URL"`** (read-only) — Created automatically when content is imported from a website. Contains the scraped page content with the source URL. Cannot be set on creation.
:::

**Shell**

```shell
curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'
```

**Python**

```python
import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()
```

**Response** `201 Created`

```json
{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "embed_state": "pending",
  "refresh_failure_reason": "",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}
```

| Field | Description |
|-------|-------------|
| `id` <br/> integer | Article numeric ID. This is the canonical identifier used in all URL paths |
| `article_id` <br/> string | Legacy string identifier. May be empty — use `id` instead |
| `type` <br/> string | `"Article"`, `"Paragraph"`, or `"URL"` |
| `title` <br/> string | Article title |
| `description` <br/> string | Article description |
| `content` <br/> string | Article content |
| `deploy_state` <br/> string | `"draft"` or `"published"` — a label only (see note below) |
| `embed_state` <br/> string or null | Whether the article is live: `"pending"`, `"embedding"`, `"embedded"`, or `"failed"` (see note below) |
| `state` <br/> string | Internal processing status (see note below) |
| `refresh_failure_reason` <br/> string | Why the latest URL refresh failed. Empty when no classified refresh failure is stored |
| `version` <br/> integer or null | Current version number |
| `max_available_version` <br/> integer or null | Highest available version |
| `url` <br/> string or null | Source URL (for URL-type articles) |
| `tags` <br/> array of strings | Associated tags |
| `created_timestamp` <br/> string | Creation date |
| `last_modified_timestamp` <br/> string | Last modification date |
| `downloaded_timestamp` <br/> string | Download date |
| `last_updated_timestamp` <br/> string | Last update date |
| `last_updated_from_external_source_timestamp` <br/> string or null | Last external source update |

:::note[Understanding Article States]
Articles have three state fields. Only one of them tells you whether your AI Agent is using the article:

- **`embed_state`**: The one that matters. `"pending"` and `"embedding"` mean the article is still being processed; `"embedded"` means it is live and your AI Agent is using it; `"failed"` means processing didn't complete and the article is not being used. This is the field to poll after a write.
- **`deploy_state`**: `"draft"` or `"published"`. A label for your own organisation only — it does **not** affect whether the AI uses the article.
- **`state`**: Internal content-fetching status. For most API users this can be ignored. On a URL article, `"refresh_failed"` means the latest refresh did not replace the saved content.
- **`refresh_failure_reason`**: A stable category for a classified URL refresh failure: `"http_error"`, `"soft_404"`, `"off_domain_redirect"`, `"auth_wall"`, `"error_page"`, `"empty_content"`, or `"thin_content"`. It can be empty when the scrape failed before Quickchat could classify the page. The last saved content remains live unless `embed_state` also failed.
:::

## List Articles

**Scope: read_all**

`GET https://app.quickchat.ai/v1/api/knowledge_base/articles/`

**Query Parameters**

| Parameter | Description |
|-----------|-------------|
| `limit` <br/> integer | Items per page |
| `offset` <br/> integer | Items to skip |
| `types` <br/> string | Filter by type: `Article`, `Paragraph`, `URL` |
| `tags` <br/> string | Filter by tag |
| `url` <br/> string | Filter by URL |
| `title` <br/> string | Filter by title |
| `query` <br/> string | Search by content |

**Shell**

```shell
curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'
```

**Python**

```python
import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()
```

**Response** `200 OK`

```json
{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "embed_state": "embedded",
      "refresh_failure_reason": "",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}
```

:::note
The list response does **not** include the `content` field. Use [Get Article](/docs/api-reference/knowledge-base/articles#get-article) to retrieve the full content of a specific article.
:::

## Get Article

**Scope: read_all**

`GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}`

**Shell**

```shell
curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'
```

**Python**

```python
import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()
```

**Response** `200 OK` — Returns the full article object (same schema as [Create Article](/docs/api-reference/knowledge-base/articles#create-article) response), including the `content` field.

## Update Article

**Scope: write_all**

`PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}`

**Request Body**

| Parameter | Description |
|-----------|-------------|
| `content` <br/> string | Updated article content |
| `title` <br/> string | Updated title |
| `tags` <br/> array of strings | Updated tags |
| `save_mode` <br/> string | `"draft"` (default) or `"publish"` |

:::caution
The `save_mode: "draft"` option only sets the `deploy_state` flag — it does **not** hold the content back from the AI. A draft article is processed and used exactly like a published one. Don't rely on it to stage content; only write an article once you're ready for it to go live.
:::

**Shell**

```shell
curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'
```

**Python**

```python
import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()
```

**Response** `200 OK` — Returns the updated article object.

## Delete Articles

Delete one or more articles by ID.

**Scope: write_all**

`DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/`

**Request Body** — JSON array of article IDs.

**Shell**

```shell
curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'
```

**Python**

```python
import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)
```

**Response** `200 OK`

## Search Articles

Search through article content with text matching.

**Scope: read_all**

`GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search`

**Query Parameters**

| Parameter | Description |
|-----------|-------------|
| `query` <br/> string, required | Search query |
| `is_case_insensitive` <br/> boolean | Case-insensitive search (default: `true`) |
| `with_title_url_and_tags` <br/> boolean | Include title/URL/tags in search (default: `true`) |
| `strict_search` <br/> boolean | Require exact match (default: `false`) |
| `num_of_display_articles` <br/> integer | Number of articles to display (default: `5`) |
| `num_of_data_articles` <br/> integer | Number of articles to search (default: `15`) |

**Shell**

```shell
curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'
```

**Python**

```python
import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()
```

**Response** `200 OK`

```json
{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}
```

## List Paragraphs

List all Paragraph-type articles. Paragraphs are short standalone text entries without a title — as opposed to full Articles which have both a title and content body.

**Scope: read_all**

`GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs`

**Query Parameters**

| Parameter | Description |
|-----------|-------------|
| `limit` <br/> integer | Items per page |
| `offset` <br/> integer | Items to skip |
| `query` <br/> string | Filter by content |

**Shell**

```shell
curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'
```

**Python**

```python
import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()
```

**Response** `200 OK`

```json
{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}
```

---

[public-lab-action-request-post]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/action-request/lab/post/?placement=docs-articles-api-action-request-post-v1

[public-lab-action-response-post]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/action-response/lab/post/?placement=docs-articles-api-action-response-post-v1
