Knowledge Stores - Hexel Studio

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

Create a knowledge store

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

string

required

Display name for the store.

integer

default:"800"

Tokens per chunk. Range: 100–4000.

integer

default:"100"

Token overlap between adjacent chunks to preserve context. Range: 0–500.

string

default:"recursive"

How content is split. One of recursive, markdown, conversation.

string

Which provider generates embeddings. One of openai, bedrock, custom.

integer

default:"1024"

Vector size for embeddings. Range: 128–4096.

Response

string

Unique store identifier.

string

Display name.

string

Current store state: active, provisioning, error, or deleted.

string

ISO 8601 creation timestamp.

Search a knowledge store

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

string

required

The search query. Length: 1–10,000 characters.

integer

default:"10"

Number of results to return. Range: 1–100.

float

Minimum similarity score to include a result. Optional; omit to return all top_k results regardless of score.

Search response

array

Array of matching chunks, each containing chunk_id, content, score, and metadata.

List knowledge stores

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

Delete a knowledge store

curl -X DELETE https://api.hexelstudio.com/data/v1/knowledge/YOUR_STORE_ID \
  -H "Authorization: Bearer $TOKEN"

Deleting a store removes all its chunks and embeddings. This cannot be undone.

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

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.

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.

Create returns 400 VALIDATION

Check the configuration ranges: chunk_size 100–4000, chunk_overlap 0–500, embedding_dimensions 128–4096.

Rate limits

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

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.

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.

Documents & Uploads

Add files to a store.

Connectors

Keep stores synced with external data.

Context Bundles

Assemble retrieved context for a run.

Knowledge & Memory

Conceptual overview of stores and memory.

Next steps

Continue to Memory.

​Key concepts

​Store states

​How it works

​Create a knowledge store

​Request parameters

​Response

​Search a knowledge store

​Search parameters

​Search response

​List knowledge stores

​Delete a knowledge store

​Configuration reference

​Errors

​Security

​Troubleshooting

​Rate limits

​Related pages

Documents & Uploads

Connectors

Context Bundles

Knowledge & Memory

​Next steps

Key concepts

Store states

How it works

Create a knowledge store

Request parameters

Response

Search a knowledge store

Search parameters

Search response

List knowledge stores

Delete a knowledge store

Configuration reference

Errors

Security

Troubleshooting

Rate limits

Related pages

Next steps