---
title: "Create a RAG collection"
method: POST
path: "/v1/rag/collections"
tags: ["RAG"]
---

# Create a RAG collection

`POST /v1/rag/collections`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/rag/collections`
- Auth: HTTP bearer

Requires tools:exec; a tools:read bearer lists collections but cannot create one.

## Request body

- object
  - `name` string, required
  - `folderPath` string, required: Absolute path to an existing folder to index. A collection indexes the folder's whole subtree, so a folder that holds or sits inside a credential store (such as ~/.ssh, the keychains, or ToolPiper's vault and clipboard history) is refused with a 400 that says so; `~`, `~/Library`, ToolPiper's support directory and `/` are refused for that reason.
  - `embeddingModelStem` string, required: Model stem to use for embeddings (from /v1/models)
  - `chunkSize` integer
  - `chunkOverlap` integer

## Response `200`

Created collection

- RagCollection
  - `id` string, required
  - `name` string, required
  - `folderPath` string, required
  - `embeddingModelStem` string, required
  - `chunkSize` integer, required
  - `chunkOverlap` integer, required
  - `status` 'empty' | 'indexed' | 'stale' | 'error', required
  - `lastIndexedAt` string, date-time, nullable
  - `documentCount` integer, required
  - `chunkCount` integer, required
  - `dimensions` integer, required
  - `errorMessage` string, nullable
  - `projectId` string: The project whose knowledge this collection is; it indexes that project's materials and is changed through the project. Absent for a collection a person made.

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)