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

> 外部システムのドキュメントを Profound の Knowledge Base に同期し、API から検索します

このガイドでは、Guru などの外部システムのドキュメントを Profound の Knowledge Base に同期する方法を説明します。すべての例で API キーによる認証が必要です。

<Note>
  Knowledge Base は Profound アプリで作成する必要があります。API から Knowledge Base を作成することはできません。`your_api_key`、`your_knowledge_base_id`、`your_organization_id` は実際の値に置き換えてください。
</Note>

## ドキュメント同期の手順

外部システムのドキュメントやフォルダをミラーリングするには、次の流れで操作します。

1. [**List Knowledge Bases**](/api-reference/knowledge-bases/list-knowledge-bases) を使用して Knowledge Base の ID を確認します。
2. 必要に応じて [**Add Folder**](/api-reference/knowledge-bases/add-folder) を使用して、ソースのフォルダをミラーリングします。
3. [**Add Document**](/api-reference/knowledge-bases/add-document) を使用して、各ソースドキュメントをアップロードします。
4. 冪等な再同期には [**Update Document**](/api-reference/knowledge-bases/update-document) を使用します。
5. ソースシステムからコンテンツが削除された場合は、[**Delete Document**](/api-reference/knowledge-bases/delete-document) または [**Delete Folder**](/api-reference/knowledge-bases/delete-folder) を使用します。

### 1. Knowledge Base の一覧を取得する

まず、同期先の Knowledge Base の ID を取得します。ここで返される `id` は、その他すべての Knowledge Base リクエストで `knowledge_base_id` パスパラメータとして必要になります。

```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": {}
}
```

API キーが複数の組織にアクセスできる場合は、リクエストに `organization_id` を指定します。

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

API キーが複数の組織にまたがる場合は、以降のリクエストでも同じクエリパラメータを使用してください。

### 2. フォルダを追加する

フォルダは作成時点では空です。ドキュメントの格納先フォルダはあらかじめ存在している必要があるため、ドキュメントをアップロードする前にソースの階層を作成し、`Engineering/API` のようなフォルダパスを使用して Guru の階層をミラーリングしてください。ネストされたフォルダより先に親フォルダを作成します。既に存在するフォルダを作成しようとすると `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. ドキュメントを追加する

ドキュメントを JSON で追加するには、テキストを `text` フィールドで送信します。`folder` は省略可能で、指定した場合はドキュメントを格納するフォルダパスになります。

```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."
}
```

ファイルを multipart フォームデータとしてアップロードすることもできます。これは、ソースシステムがドキュメントファイルを直接提供する場合に便利です。

```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"
```

どちらの形式でも、ドキュメント名、パス、フォルダが返されます。

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

ドキュメントの追加では既存のドキュメントは上書きされません。ドキュメントパスが既に存在する場合、リクエストは `409 Conflict` を返します。パスが既に存在する場合は、代わりに更新を使用してください。

### 4. ドキュメントを更新する

更新は、対象パスにある既存のドキュメントを上書きします。JSON リクエストには、追加時と同じ `name`、`text`、および省略可能な `folder` フィールドを指定します。

```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 アップロードでは、同じ `name` と省略可能な `folder` フィールドを使用し、`text` の代わりに `file` を指定します。

```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"
```

更新は既存のフォルダ内にある既存のドキュメントパスを対象とします。フォルダが存在しない場合は `404 Not Found` が返されます。

### 5. ドキュメントを削除する

ドキュメントを削除するには、JSON リクエストボディでその名前を送信します。ネストされたドキュメントを削除する場合は、名前に `folder` を含めてください。

```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. フォルダを削除する

空のフォルダを削除するには、`recursive` を `false` (デフォルト) に設定します。

```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
}
```

フォルダが空でない場合、リクエストは `409 Conflict` を返し、何も削除されません。フォルダとその中身をすべて削除するには、`recursive` を `true` に設定します。

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

### 7. Knowledge Base を検索する

必須の `query` と、1 から 100 までの `top_k` を指定して検索します。スニペットではなくページ全体のコンテンツを取得するには、`return_full_page` を `true` に設定します。

```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` は、指定したタグのいずれかを持つドキュメントに一致します。`filters.folders` は検索対象をフォルダパスに限定するもので、現在は 1 つのフォルダのみ指定できます。

各結果には、`id`、関連度を示す `score`、`metadata`、および一致した `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>
  外部システムとの同期では、ソースドキュメントをループ処理し、フォルダパスを使用してソースの階層をミラーリングし、冪等な再同期には `PUT` を、ソースから削除されたドキュメントには `DELETE` を使用してください。
</Tip>