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

# Knowledge Stores

> Create searchable collections of content with configurable chunking and embedding.

Use a knowledge store when your agent needs to answer questions grounded in *your* data — internal docs, company policies, product FAQs — rather than relying on whatever the model learned during training. For example, a support agent that answers billing questions should search your help-center articles, not improvise from general internet knowledge. You upload or connect that content once, and the platform makes it searchable by meaning.

A knowledge store is a searchable collection of content. You ingest documents or connect data sources, the platform chunks and embeds the content, and your agents retrieve it with semantic search.

## Key concepts

| Term                | Meaning                                               |
| ------------------- | ----------------------------------------------------- |
| **Knowledge store** | A collection of ingested, searchable content.         |
| **Chunk**           | A segment of a document, sized for retrieval.         |
| **Embedding**       | A vector representation used for semantic similarity. |
| **Semantic search** | Retrieval ranked by meaning, not exact keywords.      |

## Store states

| State          | Meaning                                |
| -------------- | -------------------------------------- |
| `active`       | Ready for ingestion and search.        |
| `provisioning` | Being set up; not yet searchable.      |
| `error`        | Configuration or infrastructure issue. |
| `deleted`      | Soft-deleted; no longer accessible.    |

## How it works

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/knowledge-search.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=7e57ef94dc8e2d5bf3660df858022778" alt="Knowledge search" width="1536" height="1024" data-path="assets/diagrams/knowledge-search.png" />

## Create a knowledge store

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-docs",
    "chunking_strategy": "recursive",
    "chunk_size": 512,
    "chunk_overlap": 64,
    "embedding_provider": "openai",
    "embedding_dimensions": 1024
  }'
```

### Request parameters

<ParamField body="name" type="string" required>
  Display name for the store.
</ParamField>

<ParamField body="chunk_size" type="integer" default="800">
  Tokens per chunk. Range: 100–4000.
</ParamField>

<ParamField body="chunk_overlap" type="integer" default="100">
  Token overlap between adjacent chunks to preserve context. Range: 0–500.
</ParamField>

<ParamField body="chunking_strategy" type="string" default="recursive">
  How content is split. One of `recursive`, `markdown`, `conversation`.
</ParamField>

<ParamField body="embedding_provider" type="string">
  Which provider generates embeddings. One of `openai`, `bedrock`, `custom`.
</ParamField>

<ParamField body="embedding_dimensions" type="integer" default="1024">
  Vector size for embeddings. Range: 128–4096.
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique store identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Display name.
</ResponseField>

<ResponseField name="state" type="string">
  Current store state: `active`, `provisioning`, `error`, or `deleted`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Search a knowledge store

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do refunds work?",
    "top_k": 5,
    "score_threshold": 0.7
  }'
```

### Search parameters

<ParamField body="query" type="string" required>
  The search query. Length: 1–10,000 characters.
</ParamField>

<ParamField body="top_k" type="integer" default="10">
  Number of results to return. Range: 1–100.
</ParamField>

<ParamField body="score_threshold" type="float">
  Minimum similarity score to include a result. Optional; omit to return all top\_k results regardless of score.
</ParamField>

### Search response

<ResponseField name="results" type="array">
  Array of matching chunks, each containing `chunk_id`, `content`, `score`, and `metadata`.
</ResponseField>

## List knowledge stores

```bash theme={"dark"}
curl "https://api.hexelstudio.com/data/v1/knowledge?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

## Delete a knowledge store

```bash theme={"dark"}
curl -X DELETE https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID \
  -H "Authorization: Bearer $TOKEN"
```

<Warning>
  Deleting a store removes all its chunks and embeddings. This cannot be undone.
</Warning>

## Configuration reference

| Setting                | Range                                     | Default     | Purpose                       |
| ---------------------- | ----------------------------------------- | ----------- | ----------------------------- |
| `chunk_size`           | 100–4000                                  | 800         | Tokens per chunk.             |
| `chunk_overlap`        | 0–500                                     | 100         | Token overlap between chunks. |
| `embedding_dimensions` | 128–4096                                  | 1024        | Embedding vector size.        |
| `chunking_strategy`    | `recursive` / `markdown` / `conversation` | `recursive` | How content is split.         |
| `embedding_provider`   | `openai` / `bedrock` / `custom`           | —           | Provider for embeddings.      |

## Errors

| `code`                   | HTTP | When                                                                                                                     |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------ |
| `VALIDATION`             | 400  | `chunk_size`, `chunk_overlap`, `embedding_dimensions`, or `top_k` is out of range, or `query` exceeds 10,000 characters. |
| `AUTH.PERMISSION_DENIED` | 403  | Missing `data-platform:knowledge:read` (search) or `data-platform:knowledge:write` (create/ingest).                      |
| `RESOURCE.NOT_FOUND`     | 404  | The knowledge store doesn't exist.                                                                                       |

## Security

| Concern          | Detail                                                                                                                  |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Read permission  | `data-platform:knowledge:read` — search and retrieve from a store.                                                      |
| Write permission | `data-platform:knowledge:write` — create stores, ingest documents, run connectors, delete.                              |
| Scoping          | Stores are scoped to your organization, workspace, and environment.                                                     |
| Storage          | Content and embeddings live on platform-managed storage.                                                                |
| Sensitive data   | Do not ingest secrets or credentials. Any agent with read access to the store can retrieve ingested content via search. |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Search returns irrelevant or low-quality results">
    Tune chunking and retrieval: lower `chunk_size` for dense documents, add `chunk_overlap` to preserve context, and set a `score_threshold` to filter weak matches. Keep each store focused on a single domain.
  </Accordion>

  <Accordion title="Newly uploaded content isn't searchable yet">
    Ingestion is asynchronous. A store in `provisioning` is still indexing; wait until it reports `active` before relying on search.
  </Accordion>

  <Accordion title="Create returns 400 VALIDATION">
    Check the configuration ranges: `chunk_size` 100–4000, `chunk_overlap` 0–500, `embedding_dimensions` 128–4096.
  </Accordion>
</AccordionGroup>

## Rate limits

10,000 requests per organization per hour. Pagination: `page` >= 1, `page_size` 1–100 (default 20).

<AccordionGroup>
  <Accordion title="Common errors">
    | Code  | Meaning                                                |
    | ----- | ------------------------------------------------------ |
    | `404` | Store not found or deleted.                            |
    | `422` | Invalid parameter (e.g., chunk\_size out of range).    |
    | `429` | Rate limit exceeded. Retry after the indicated window. |
  </Accordion>

  <Accordion title="Tuning chunk_size">
    Very large chunks dilute relevance; very small chunks lose surrounding context. Start near 512 with 50–100 overlap and adjust based on retrieval quality. Use `markdown` strategy for structured documents and `conversation` for chat logs.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Documents & Uploads" icon="file-arrow-up" href="/docs/data-platform/documents">
    Add files to a store.
  </Card>

  <Card title="Connectors" icon="plug" href="/docs/data-platform/connectors">
    Keep stores synced with external data.
  </Card>

  <Card title="Context Bundles" icon="box" href="/docs/data-platform/context-bundles">
    Assemble retrieved context for a run.
  </Card>

  <Card title="Knowledge & Memory" icon="brain" href="/docs/concepts/knowledge-and-memory">
    Conceptual overview of stores and memory.
  </Card>
</CardGroup>

## Next steps

Continue to [Memory](/docs/data-platform/memory).