# Knowledge

Knowledge sources for RAG

## List knowledge sources

> Returns a list of knowledge sources (RAG documents). Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge":{"get":{"summary":"List knowledge sources","description":"Returns a list of knowledge sources (RAG documents). Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"},"description":"Page number for pagination"}],"responses":{"200":{"description":"A list of knowledge sources","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSource"}}}}}},"tags":["Knowledge"]}}}}
```

## Create a text knowledge source

> Create a knowledge source from text content. For file uploads, use POST /v1/knowledge/upload.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge":{"post":{"summary":"Create a text knowledge source","description":"Create a knowledge source from text content. For file uploads, use POST /v1/knowledge/upload.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","content"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"content":{"type":"string","maxLength":100000,"description":"The text content to index"}}}}}},"responses":{"201":{"description":"Knowledge source created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"}}}}},"tags":["Knowledge"]}}}}
```

## Request upload URL for file-based knowledge

> Get a signed URL to upload a PDF or TXT file. After uploading, call POST /v1/knowledge/{id}/confirm to trigger processing.\
> Maximum file size: 50MB.<br>

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/knowledge/upload":{"post":{"summary":"Request upload URL for file-based knowledge","description":"Get a signed URL to upload a PDF or TXT file. After uploading, call POST /v1/knowledge/{id}/confirm to trigger processing.\nMaximum file size: 50MB.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","filename","content_type"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"filename":{"type":"string"},"content_type":{"type":"string","enum":["application/pdf","text/plain"]}}}}}},"responses":{"201":{"description":"Upload URL generated","content":{"application/json":{"schema":{"type":"object","properties":{"knowledge_id":{"type":"integer"},"upload_url":{"type":"string","description":"Signed URL for file upload"},"expires_at":{"type":"string","format":"date-time"}}}}}}},"tags":["Knowledge"]}}}}
```

## Get a knowledge source

> Get a single knowledge source by ID. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge/{id}":{"get":{"summary":"Get a knowledge source","description":"Get a single knowledge source by ID. Requires Power plan or higher.","responses":{"200":{"description":"Knowledge source detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"}}}}},"tags":["Knowledge"]}}}}
```

## Delete a knowledge source

> Delete a knowledge source and its embeddings. Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/knowledge/{id}":{"delete":{"summary":"Delete a knowledge source","description":"Delete a knowledge source and its embeddings. Requires Power plan or higher.","responses":{"204":{"description":"Knowledge source deleted"}},"tags":["Knowledge"]}}}}
```

## Update a knowledge source

> Update knowledge source metadata (name, description, etc.). Requires Power plan or higher.

```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Knowledge","description":"Knowledge sources for RAG"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"KnowledgeSource":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["text","file","url"]},"indexing":{"type":"object","nullable":true,"properties":{"chunks_indexed":{"type":"integer"},"total_chunks":{"type":"integer"},"was_limited":{"type":"boolean"},"indexed_at":{"type":"string","format":"date-time","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/v1/knowledge/{id}":{"patch":{"summary":"Update a knowledge source","description":"Update knowledge source metadata (name, description, etc.). Requires Power plan or higher.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"site_id":{"type":"string","format":"uuid","nullable":true},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Knowledge source updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSource"}}}}},"tags":["Knowledge"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/rest-api/knowledge.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.