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

# Knowledge Bases

> Sync documents into a Profound knowledge base and search them.

This guide shows how to sync documents from an external system such as Guru into a Profound knowledge base. All examples require authentication with an API key.

<Note>
  Knowledge bases must be created in the Profound app. The API cannot create a knowledge base. Replace `your_api_key`, `your_knowledge_base_id`, and `your_organization_id` with your actual values.
</Note>

## Syncing documents walkthrough

Use this flow to mirror documents and folders from an external system:

1. Use [**List Knowledge Bases**](/api-reference/knowledge-bases/list-knowledge-bases) to find the knowledge base ID.
2. Use [**Add Folder**](/api-reference/knowledge-bases/add-folder) to mirror source folders when needed.
3. Use [**Add Document**](/api-reference/knowledge-bases/add-document) to upload each source document.
4. Use [**Update Document**](/api-reference/knowledge-bases/update-document) for idempotent re-syncs.
5. Use [**Delete Document**](/api-reference/knowledge-bases/delete-document) or [**Delete Folder**](/api-reference/knowledge-bases/delete-folder) when content is removed from the source system.

### 1. List Knowledge Bases

First, get the ID of the knowledge base you want to sync. The `id` returned here is required as the `knowledge_base_id` path parameter for every other Knowledge Base request.

```http theme={null}
GET /v1/knowledge-bases HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "data": [
    {
      "id": "your_knowledge_base_id",
      "name": "Product Documentation",
      "slug": "product-documentation",
      "description": "Product guides and reference material",
      "created_at": "2026-04-24T19:03:15.459951Z"
    }
  ],
  "pagination": {}
}
```

If your API key can access multiple organizations, pass `organization_id` on the request:

```http theme={null}
GET /v1/knowledge-bases?organization_id=your_organization_id HTTP/1.1
X-API-Key: your_api_key
```

Use the same query parameter on subsequent requests when the API key spans multiple organizations.

### 2. Add a Folder

Folders are empty when created. A document's folder must already exist, so create the source hierarchy before uploading documents, and use folder paths such as `Engineering/API` to mirror the hierarchy in Guru. Create parent folders before their nested folders. Creating a folder that already exists returns `409 Conflict`.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/folders HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "path": "Engineering"
}
```

```json theme={null}
{
  "message": "Folder added.",
  "path": "Engineering"
}
```

### 3. Add a Document

Add a document as JSON by sending its text in the `text` field. `folder` is optional; when provided, it is the folder path containing the document.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "authentication.md",
  "folder": "Engineering",
  "text": "# Authentication\n\nUse an API key to authenticate requests."
}
```

You can also upload a file as multipart form data. This is useful when your source system provides document files directly:

```bash theme={null}
curl -X POST "https://api.tryprofound.com/v1/knowledge-bases/your_knowledge_base_id/documents" \
  -H "X-API-Key: your_api_key" \
  -F "name=authentication.md" \
  -F "folder=Engineering" \
  -F "file=@./authentication.md"
```

Both forms return the document name, path, and folder:

```json theme={null}
{
  "message": "Document added.",
  "name": "authentication.md",
  "path": "Engineering/authentication.md",
  "folder": "Engineering"
}
```

Adding a document does not overwrite an existing document: if the document path already exists, the request returns `409 Conflict`. Use update instead when the path already exists.

### 4. Update a Document

Update overwrites an existing document at the target path. The JSON request has the same `name`, `text`, and optional `folder` fields as add:

```http theme={null}
PUT /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "authentication.md",
  "folder": "Engineering",
  "text": "# Authentication\n\nUse the latest API key instructions."
}
```

Multipart uploads use the same `name` and optional `folder` fields, with `file` replacing `text`:

```bash theme={null}
curl -X PUT "https://api.tryprofound.com/v1/knowledge-bases/your_knowledge_base_id/documents" \
  -H "X-API-Key: your_api_key" \
  -F "name=authentication.md" \
  -F "folder=Engineering" \
  -F "file=@./authentication.md"
```

Update targets an existing document path in an existing folder; a missing folder returns `404 Not Found`.

### 5. Delete a Document

Delete a document by sending its name in a JSON request body. Include `folder` in the name when deleting a nested document:

```http theme={null}
DELETE /v1/knowledge-bases/your_knowledge_base_id/documents HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "name": "Engineering/authentication.md"
}
```

### 6. Delete a Folder

Delete an empty folder by setting `recursive` to `false` (the default):

```http theme={null}
DELETE /v1/knowledge-bases/your_knowledge_base_id/folders HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "path": "Engineering",
  "recursive": false
}
```

If the folder is not empty, the request returns `409 Conflict` and nothing is deleted. To delete the folder and all of its contents, set `recursive` to `true`:

```json theme={null}
{
  "path": "Engineering",
  "recursive": true
}
```

### 7. Search a Knowledge Base

Search with a required `query` and `top_k` between 1 and 100. Set `return_full_page` to `true` to request full page content instead of snippets.

```http theme={null}
POST /v1/knowledge-bases/your_knowledge_base_id/search HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "query": "How do I authenticate?",
  "top_k": 5,
  "return_full_page": false,
  "filters": {
    "tags": ["api"],
    "folders": ["Engineering"]
  }
}
```

`filters.tags` matches documents with any of the supplied tags. `filters.folders` limits the search to folder paths and currently accepts exactly one folder.

Each result includes an `id`, relevance `score`, `metadata`, and matched `content`:

```json theme={null}
{
  "data": [
    {
      "id": "Engineering/authentication.md",
      "score": 0.94,
      "metadata": {
        "folder_path": "Engineering",
        "source_filename": "authentication.md"
      },
      "content": "Use an API key to authenticate requests."
    }
  ],
  "pagination": {}
}
```

<Tip>
  For an external-system sync, loop over the source documents, use their folder paths to mirror the source hierarchy, use `PUT` for idempotent re-syncs, and use `DELETE` for documents removed from the source.
</Tip>