> ## 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.

# Context Bundles

> Assemble grounded context from knowledge and memory for a task run.

Use a context bundle when you need to assemble the right context for a specific run — gathering relevant knowledge and memory into one place before an orchestration task starts. Think of it as packing a briefcase: you decide which knowledge stores and memory stores matter for this job, and the bundle gives the task a single, consistent view to query against.

A context bundle is a prepared set of grounded context drawn from knowledge stores and memory, assembled for a specific run. It provides a consistent, queryable view of the information a task needs, and can be refreshed as underlying sources change.

## Operations

| Operation | Method | Endpoint                                       |
| --------- | ------ | ---------------------------------------------- |
| Create    | `POST` | `/data/v1/context-bundles`                     |
| Get       | `GET`  | `/data/v1/context-bundles/{bundle_id}`         |
| Query     | `POST` | `/data/v1/context-bundles/{bundle_id}/query`   |
| Refresh   | `POST` | `/data/v1/context-bundles/{bundle_id}/refresh` |

## Create a context bundle

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/context-bundles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_store_ids": ["YOUR_STORE_ID"],
    "memory_store_ids": ["YOUR_MEMORY_STORE_ID"]
  }'
```

<ParamField body="knowledge_store_ids" type="string[]">
  Knowledge stores to include in this bundle.
</ParamField>

<ParamField body="memory_store_ids" type="string[]">
  Memory stores to include in this bundle.
</ParamField>

### Response

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

<ResponseField name="knowledge_store_ids" type="string[]">
  Included knowledge stores.
</ResponseField>

<ResponseField name="memory_store_ids" type="string[]">
  Included memory stores.
</ResponseField>

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

## Get a context bundle

```bash theme={"dark"}
curl https://api.hexelstudio.com/data/v1/context-bundles/YOUR_BUNDLE_ID \
  -H "Authorization: Bearer $TOKEN"
```

## Query a context bundle

Retrieve grounded context from within the bundle using semantic search.

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/context-bundles/YOUR_BUNDLE_ID/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund policy",
    "top_k": 5
  }'
```

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

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

### Query response

<ResponseField name="results" type="array">
  Ranked results from across the bundle's stores, each with `content`, `score`, `source_type`, and `source_id`.
</ResponseField>

## Refresh a context bundle

Updates the bundle to reflect current content in its underlying stores. Call this after ingesting new documents or writing new memory items.

```bash theme={"dark"}
curl -X POST https://api.hexelstudio.com/data/v1/context-bundles/YOUR_BUNDLE_ID/refresh \
  -H "Authorization: Bearer $TOKEN"
```

## Errors

| `code`                   | HTTP | When                                                      |
| ------------------------ | ---- | --------------------------------------------------------- |
| `VALIDATION`             | 400  | No sources specified, or an invalid query.                |
| `AUTH.PERMISSION_DENIED` | 403  | Missing read permission on a referenced store.            |
| `RESOURCE.NOT_FOUND`     | 404  | The bundle or a referenced knowledge store doesn't exist. |

## Security

| Concern | Detail                                                                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Access  | A bundle can only reference knowledge stores and memory stores you have `data-platform:knowledge:read` or `data-platform:memory:read` access to. |
| Scoping | Bundles are scoped to your organization, workspace, and environment.                                                                             |
| Storage | Assembled context lives on platform-managed storage for the bundle's lifetime and is deleted when the bundle is deleted.                         |

## Production recommendations

* Scope each bundle tightly to the sources a run actually needs — unrelated stores dilute retrieval.
* Refresh on a cadence that matches how often the underlying content changes; a bundle reflects its sources at assembly time.
* Reuse one bundle across related runs for consistent, reproducible context.

## Rate limits

10,000 requests per organization per hour.

<AccordionGroup>
  <Accordion title="When to refresh">
    A bundle reflects its sources at assembly time. Refresh after:

    * New documents are ingested into a referenced knowledge store.
    * A connector sync completes.
    * New memory items are written to a referenced memory store.
  </Accordion>

  <Accordion title="Bundle scoping guidance">
    Include only the stores a specific task needs. Over-broad bundles (many unrelated stores) dilute retrieval relevance. Create separate bundles for different task types.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Knowledge Stores" icon="book" href="/docs/data-platform/knowledge-stores">
    Sources for bundle content.
  </Card>

  <Card title="Memory" icon="brain" href="/docs/data-platform/memory">
    Recallable context included in bundles.
  </Card>

  <Card title="Orchestration" icon="sitemap" href="/docs/orchestration/overview">
    How bundles support task execution.
  </Card>

  <Card title="Data Platform Overview" icon="database" href="/docs/data-platform/overview">
    The full data model.
  </Card>
</CardGroup>

## Next steps

Explore [Orchestration](/docs/orchestration/overview) to put knowledge and memory to work in tasks.