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

# Chunks

> How a published article is cut into the pieces a chatbot retrieves, and how to check a draft before you publish it. Read-only.

When an article is published, it is cut into **chunks**: the pieces a chatbot searches and reads. A chatbot never retrieves a whole article at once; it retrieves the chunks that best match the question. How an article is cut decides what a chatbot can find in it.

Two read-only endpoints show the cut:

| Endpoint | Use it to |
| - | - |
| `GET /articles/{id}/chunks` | See the chunks stored for a published article. |
| `POST /articles/chunk-preview` | See how a body *would* be cut, before you create or update an article. Nothing is stored. |

## How articles are cut

* **Sections start new chunks.** Every `##` (h2) and `###` (h3) heading starts a new chunk, so a chunk never spans two sections. A heading with no text of its own before the next heading joins that next section.
* **Chunks hold up to about 2,000 characters.** A longer section is split at the most natural break available: between paragraphs, then lines, then sentences, then words.
* **Continuations overlap.** When a section is split, the next chunk opens with up to 200 characters from the end of the previous one, so a step that straddles the split keeps its context. `overlap_chars` tells you how much.
* **Tables split between rows**, with the header row repeated on every piece.
* **Images become markers** carrying their alt text, such as `![Loosen the wheel nuts](asset://…)`. An image with no alt text carries its generated description instead.

## Stored chunks

```bash cURL theme={null}
curl "https://api.awardee.com/v1/articles/2f6c1a9e-7b3d-4c8e-9a1f-5d2b7e4c3a10/chunks" \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
```

```javascript JavaScript theme={null}
const chunks = await fetch(
  `https://api.awardee.com/v1/articles/${ID}/chunks`,
  { headers: { Authorization: `Bearer ${API_KEY}` } },
).then((r) => r.json())
```

```python Python theme={null}
import requests

chunks = requests.get(
    f"https://api.awardee.com/v1/articles/{ID}/chunks",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()
```

**language** `string`

Which language's chunks to return. Defaults to the article's primary
`language`; pass a translation's language to see its chunks.

```json theme={null}
{
  "article_id": "2f6c1a9e-7b3d-4c8e-9a1f-5d2b7e4c3a10",
  "language": "en",
  "indexing_status": "indexed",
  "indexed_at": "2026-10-01T22:14:09+00:00",
  "in_sync": true,
  "chunk_count": 7,
  "chunks": [
    {
      "index": 1,
      "text": "Cleaning\n\nWarning: Let the basket, pan, and inside of the appliance cool down...",
      "char_count": 375,
      "char_start": 109,
      "char_end": 484,
      "overlap_chars": 0,
      "section_heading": "Cleaning",
      "section_path": "Cleaning",
      "section_anchor": "cleaning"
    },
    {
      "index": 2,
      "text": "Cleaning Steps\n\n- Press the power On/Off button to switch off the appliance...",
      "char_count": 1689,
      "char_start": 486,
      "char_end": 2175,
      "overlap_chars": 0,
      "section_heading": "Cleaning Steps",
      "section_path": "Cleaning > Cleaning Steps",
      "section_anchor": "cleaning-steps"
    }
  ]
}
```

**in\_sync** `boolean` *required*

`true` when the stored chunks are exactly what the article's current content
produces. `false` means the article changed after it was indexed, or indexing
hasn't finished. The stored chunks are still what chatbots search until
indexing catches up.

**section\_path** `string | null`

The section the chunk belongs to. For a chunk under an h3 it includes the
parent h2, as `"Cleaning > Cleaning Steps"`. `null` for text before the first
heading, and for chunks that changed since indexing.

**section\_anchor** `string | null`

The section's link anchor in the published article.

**char\_start** `integer | null`

Where the chunk starts in the article's **indexed text**: every chunk laid end
to end, a blank line between them, each overlap counted once. The chunk's
`text` is always exactly `indexed_text.slice(char_start, char_end)`, so a
chunk with `overlap_chars` above zero starts before the previous chunk ends.
`null` when the chunk can't be placed (when `in_sync` is `false`).

**overlap\_chars** `integer | null`

How many characters at the start of the chunk repeat the end of the previous
one, including the blank line. `0` for a chunk that starts a section.

## Previewing a draft

`POST /articles/chunk-preview` cuts a body exactly as publishing it would and returns the chunks, without creating or changing anything. It accepts `content` in the same format as [creating an article](https://docs.awardee.com/articles/object.md). The response has `chunk_count` and `chunks` in the shape above.

```bash cURL theme={null}
curl https://api.awardee.com/v1/articles/chunk-preview \
  -X POST \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e" \
  -H "Content-Type: application/json" \
  -d '{ "content": "## Replacing the seals\n\n### Part 1\n\n1. Isolate the power.\n2. Remove the housing." }'
```

```javascript JavaScript theme={null}
const preview = await fetch("https://api.awardee.com/v1/articles/chunk-preview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: draftMarkdown }),
}).then((r) => r.json())
```

```python Python theme={null}
import requests

preview = requests.post(
    "https://api.awardee.com/v1/articles/chunk-preview",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"content": draft_markdown},
).json()
```

> [!TIP]
>
> To check how a draft would be *found*, not just cut, publish it to a test
> folder and run a [retrieval preview](https://docs.awardee.com/chatbots/retrieval-preview.md) scoped to
> that folder with `folder_id`.

## What to check

* **Does each chunk stand on its own?** A chatbot may receive one chunk without its neighbours. A chunk that says "repeat the steps above" depends on text it may not have.
* **Where do long sections split?** If a split lands in the middle of a procedure, consider breaking the section into h3 sub-sections at natural points instead.
* **What fills the start of each chunk?** A long warning or preamble repeated at the top of every part pushes the steps later in each chunk. When a chatbot runs its own follow-up search, it reads only the first 800 characters of each chunk.

Both endpoints require the `articles.view` scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.