{ "openapi": "3.0.1", "info": { "title": "ナレッジAPI", "description": "ナレッジベース（データセット）、ドキュメント、セグメントの管理API。作成、取得、設定が可能です。", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", "description": "ナレッジAPIのベースURL。", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", "description": "APIの実際のベースURL" } } } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "データセット", "description": "ナレッジベース（データセット）の管理に関連する操作。" }, { "name": "ドキュメント", "description": "データセット内のドキュメントの作成、更新、管理のための操作。" }, { "name": "チャンク", "description": "ドキュメントのチャンク（セグメント）の管理のための操作。" }, { "name": "メタデータ・タグ", "description": "データセットタグとメタデータの管理のための操作。" }, { "name": "モデル", "description": "利用可能なモデルの取得のための操作。" } ], "paths": { "/datasets": { "post": { "tags": [ "データセット" ], "summary": "空のナレッジベースを作成", "description": "指定された設定で新しい空のナレッジベース（データセット）を作成します。", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetRequest" } } } }, "responses": { "200": { "description": "データセットの作成に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "409": { "$ref": "#/components/responses/DatasetNameDuplicate" } } }, "get": { "tags": [ "データセット" ], "summary": "ナレッジベースリストを取得", "description": "ページネーションとフィルタリングのオプション付きでナレッジベースのリストを取得します。", "operationId": "listDatasets", "parameters": [ { "name": "keyword", "in": "query", "description": "名前でデータセットをフィルタするための検索キーワード。", "schema": { "type": "string" } }, { "name": "tag_ids", "in": "query", "description": "フィルタするタグIDのリスト。データセットは指定されたすべてのタグを持つ必要があります。", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "page", "in": "query", "description": "ページネーションのページ番号。", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "include_all", "in": "query", "description": "すべてのデータセットを含めるかどうか。これはワークスペースオーナーにのみ有効です。", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "データセットのページネーションリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetListResponse" } } } } } } }, "/datasets/{dataset_id}": { "get": { "tags": [ "データセット" ], "summary": "ナレッジベース詳細を取得", "description": "IDで特定のナレッジベースの詳細情報を取得します。", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "データセットに関する詳細情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDetail" } } } } } }, "patch": { "tags": [ "データセット" ], "summary": "ナレッジベースを更新", "description": "特定のナレッジベースの設定を更新します。", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetRequest" } } } }, "responses": { "200": { "description": "データセット詳細の更新に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDetail" } } } }, "409": { "$ref": "#/components/responses/DatasetNameDuplicate" } } }, "delete": { "tags": [ "データセット" ], "summary": "ナレッジベースを削除", "description": "ナレッジベースとそれに関連するすべてのドキュメントとデータを削除します。", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "削除するナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "データセットの削除に成功しました。" } } } }, "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "ドキュメント" ], "summary": "テキストからドキュメントを作成", "description": "テキストコンテンツから既存のナレッジベース内に新しいドキュメントを直接作成します。", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ドキュメントを追加するナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentByTextRequest" } } } }, "responses": { "200": { "description": "ドキュメントが正常に作成され、インデックス化されています。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "ドキュメント" ], "summary": "ファイルからドキュメントを作成", "description": "ファイルをアップロードして既存のナレッジベース内に新しいドキュメントを作成します。", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ドキュメントを追加するナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "ドキュメントメタデータと処理ルールを含むJSON文字列。詳細は`CreateDocumentByFileRequestData`スキーマを参照してください。", "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}}}" }, "file": { "type": "string", "format": "binary", "description": "アップロードするファイル。" } } } } } }, "responses": { "200": { "description": "ドキュメントが正常に作成され、インデックス化されています。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } }, "400": { "$ref": "#/components/responses/FileError" }, "413": { "$ref": "#/components/responses/FileTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedFileType" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { "post": { "tags": [ "ドキュメント" ], "summary": "テキストでドキュメントを更新", "description": "テキストを使用して既存のドキュメントのコンテンツまたは設定を更新します。", "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ドキュメントを含むナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "更新するドキュメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentByTextRequest" } } } }, "responses": { "200": { "description": "ドキュメントが正常に更新されました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ "ドキュメント" ], "summary": "ファイルでドキュメントを更新", "description": "新しいファイルをアップロードして既存のドキュメントを更新し、そのコンテンツを置き換えます。", "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ドキュメントを含むナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "更新するドキュメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "オプションのドキュメント名と処理ルールを含むJSON文字列。`UpdateDocumentByFileRequestData`スキーマを参照してください。", "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" }, "file": { "type": "string", "format": "binary", "description": "アップロードする新しいファイル。" } } } } } }, "responses": { "200": { "description": "ドキュメントが正常に更新されました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ "ドキュメント" ], "summary": "ドキュメント埋め込みステータス（進捗）を取得", "description": "ドキュメントのバッチのインデックス化ステータスを取得し、埋め込みと処理の進捗を表示します。", "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "batch", "in": "path", "required": true, "description": "ドキュメント作成エンドポイントから返されるバッチ番号。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "バッチ内のドキュメントのインデックス化ステータス。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IndexingStatus" } } } } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}": { "get": { "tags": [ "ドキュメント" ], "summary": "ドキュメント詳細を取得", "description": "処理ルールとステータスを含む単一ドキュメントの詳細情報を取得します。", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "metadata", "in": "query", "description": "メタデータフィルタ：`all`はすべてのメタデータを返し、`only`はカスタムメタデータのみを返し、`without`はメタデータを返しません。", "schema": { "type": "string", "enum": [ "all", "only", "without" ], "default": "all" } } ], "responses": { "200": { "description": "ドキュメントに関する詳細情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } } } } }, "delete": { "tags": [ "ドキュメント" ], "summary": "ドキュメントを削除", "description": "ナレッジベースから特定のドキュメントを削除します。", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "削除するドキュメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "ドキュメントの削除に成功しました。" } } } }, "/datasets/{dataset_id}/documents": { "get": { "tags": [ "ドキュメント" ], "summary": "ナレッジベースのドキュメントリストを取得", "description": "指定されたナレッジベース内のすべてのドキュメントのページネーションリストを取得します。", "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "ドキュメント名で検索するキーワード。", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "ページネーションのページ番号。", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "ドキュメントのページネーションリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } } } } } }, "/datasets/{dataset_id}/documents/status/{action}": { "patch": { "tags": [ "ドキュメント" ], "summary": "ドキュメントステータスを更新", "description": "1つまたは複数のドキュメントのステータスを更新するバッチアクションを実行します（例：有効化、無効化、アーカイブ）。", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "description": "ドキュメントに対して実行するアクション。", "schema": { "type": "string", "enum": [ "enable", "disable", "archive", "un_archive" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "description": "アクションを実行するドキュメントIDのリスト。", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "チャンク" ], "summary": "ドキュメントにチャンクを追加", "description": "特定のドキュメントに1つまたは複数の新しいチャンク（セグメント）を追加します。手動でキュレートされたコンテンツを追加するのに便利です。", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentsRequest" } } } }, "responses": { "200": { "description": "新しく作成されたセグメントのリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentListResponse" } } } } } }, "get": { "tags": [ "チャンク" ], "summary": "ドキュメントからチャンクを取得", "description": "特定のドキュメントからチャンク（セグメント）のページネーションリストを取得します。", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "コンテンツでセグメントをフィルタするキーワード。", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "インデックス化ステータスでセグメントをフィルタ。", "schema": { "type": "string", "example": "completed" } }, { "name": "page", "in": "query", "description": "ページネーションのページ番号。", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "セグメントのページネーションリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentPaginatedResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "get": { "tags": [ "チャンク" ], "summary": "ドキュメント内のチャンク詳細を取得", "description": "ドキュメント内の特定のチャンク（セグメント）の詳細を取得します。", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "セグメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "セグメントに関する詳細情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDetailResponse" } } } } } }, "post": { "tags": [ "チャンク" ], "summary": "ドキュメント内のチャンクを更新", "description": "特定のチャンク（セグメント）のコンテンツ、キーワード、またはステータスを更新します。", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "更新するセグメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentRequest" } } } }, "responses": { "200": { "description": "更新されたセグメント詳細。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDetailResponse" } } } } } }, "delete": { "tags": [ "チャンク" ], "summary": "ドキュメント内のチャンクを削除", "description": "ドキュメントから特定のチャンク（セグメント）を削除します。", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "削除するセグメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "セグメントの削除に成功しました。" } } } }, "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ "データセット" ], "summary": "ナレッジベースからチャンクを取得 / テスト検索", "description": "ナレッジベースに対して検索クエリを実行し、最も関連性の高いチャンク（セグメント）を取得します。このエンドポイントは、本番環境での検索およびテスト検索の両方に使用できます。", "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "取得元のナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveRequest" } } } }, "responses": { "200": { "description": "クエリにマッチする取得されたセグメントのリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveResponse" } } } } } } }, "/workspaces/current/models/model-types/text-embedding": { "get": { "tags": [ "モデル" ], "summary": "利用可能な埋め込みモデルを取得", "description": "ナレッジベースの作成とクエリに使用できるすべての利用可能なテキスト埋め込みモデルのリストを取得します。", "operationId": "getAvailableEmbeddingModels", "responses": { "200": { "description": "プロバイダー別にグループ化された利用可能な埋め込みモデルのリスト。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProvider" } } } } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ "チャンク" ], "summary": "子チャンクを作成", "description": "階層モードを使用してドキュメント内の親セグメントの下に新しい子チャンクを作成します。", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChildChunkRequest" } } } }, "responses": { "200": { "description": "子チャンクの作成に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkResponse" } } } } } }, "get": { "tags": [ "チャンク" ], "summary": "子チャンクを取得", "description": "特定の親セグメントの子チャンクのリストを取得します。", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "子チャンクをフィルタする検索キーワード。", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "ページネーションのページ番号。", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "子チャンクのページネーションリスト。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkListResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "patch": { "tags": [ "チャンク" ], "summary": "子チャンクを更新", "description": "特定の子チャンクのコンテンツを更新します。", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "child_chunk_id", "in": "path", "required": true, "description": "更新する子チャンクのID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChildChunkRequest" } } } }, "responses": { "200": { "description": "子チャンクの更新に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkResponse" } } } } } }, "delete": { "tags": [ "チャンク" ], "summary": "子チャンクを削除", "description": "特定の子チャンクを削除します。", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "child_chunk_id", "in": "path", "required": true, "description": "削除する子チャンクのID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "子チャンクの削除に成功しました。" } } } }, "/datasets/tags": { "post": { "tags": [ "メタデータ・タグ" ], "summary": "新しいナレッジベースタイプタグを作成", "description": "ナレッジベースを分類するために使用できる新しいタグを作成します。", "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "新しいタグの名前。", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "タグの作成に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } } } }, "get": { "tags": [ "メタデータ・タグ" ], "summary": "ナレッジベースタイプタグを取得", "description": "利用可能なすべてのナレッジベースタグのリストを取得します。", "operationId": "getKnowledgeTags", "responses": { "200": { "description": "タグのリスト。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } } }, "patch": { "tags": [ "メタデータ・タグ" ], "summary": "ナレッジベースタイプタグ名を変更", "description": "既存のタグの名前を更新します。", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tag_id", "name"], "properties": { "tag_id": { "type": "string", "description": "変更するタグのID。", "format": "uuid" }, "name": { "type": "string", "description": "タグの新しい名前。", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "タグの更新に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } } } }, "delete": { "tags": [ "メタデータ・タグ" ], "summary": "ナレッジベースタイプタグを削除", "description": "タグを削除します。タグはどのナレッジベースにもバインドされていない必要があります。", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tag_id"], "properties": { "tag_id": { "type": "string", "description": "削除するタグのID。", "format": "uuid" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/tags/binding": { "post": { "tags": [ "メタデータ・タグ" ], "summary": "データセットをナレッジベースタイプタグにバインド", "description": "1つまたは複数のタグを特定のナレッジベースにバインドします。", "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["target_id", "tag_ids"], "properties": { "target_id": { "type": "string", "description": "タグをバインドするデータセットのID。", "format": "uuid" }, "tag_ids": { "type": "array", "description": "バインドするタグIDのリスト。", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/tags/unbinding": { "post": { "tags": [ "メタデータ・タグ" ], "summary": "データセットとナレッジベースタイプタグのバインドを解除", "description": "ナレッジベースから特定のタグのバインドを解除します。", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["target_id", "tag_id"], "properties": { "target_id": { "type": "string", "description": "データセットのID。", "format": "uuid" }, "tag_id": { "type": "string", "description": "バインドを解除するタグのID。", "format": "uuid" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/{dataset_id}/tags": { "post": { "tags": [ "メタデータ・タグ" ], "summary": "データセットにバインドされたタグをクエリ", "description": "特定のデータセットに現在バインドされているすべてのタグを取得します。", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "データセットのID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "データセットにバインドされたタグのリスト。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "APIキー認証。すべてのAPIリクエストにおいて、Authorization HTTPヘッダーにAPIキーを含めてください。形式：Bearer {API_KEY}。**APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。**" } }, "responses": { "Success": { "description": "操作に成功しました。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, "FileError": { "description": "ファイルアップロードに関連する不正なリクエスト。`no_file_uploaded` または `too_many_files` の可能性があります。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "FileTooLarge": { "description": "ファイルサイズが上限を超えました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedFileType": { "description": "ファイルタイプが許可されていません。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "DatasetNameDuplicate": { "description": "データセット名が既に存在します。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "機械読み取り可能なエラーコード。" }, "message": { "type": "string", "description": "人間が読めるエラーメッセージ。" }, "status": { "type": "integer", "description": "HTTPステータスコード。" } }, "example": { "code": "no_file_uploaded", "message": "ファイルをアップロードしてください。", "status": 400 } }, "RetrievalModel": { "type": "object", "properties": { "search_method": { "type": "string", "description": "取得に使用する検索方法。", "enum": [ "hybrid_search", "semantic_search", "full_text_search", "keyword_search" ] }, "reranking_enable": { "type": "boolean", "description": "検索結果を改善するためのリランキングモデルを有効にするかどうか。" }, "reranking_mode": { "type": "object", "description": "リランキングモデルの設定。", "properties": { "reranking_provider_name": { "type": "string", "description": "リランクモデルのプロバイダー。" }, "reranking_model_name": { "type": "string", "description": "リランクモデルの名前。" } }, "nullable": true }, "top_k": { "type": "integer", "description": "返すトップマッチング結果の数。" }, "score_threshold_enabled": { "type": "boolean", "description": "結果をフィルタするためのスコア閾値を適用するかどうか。" }, "score_threshold": { "type": "number", "format": "float", "description": "結果に含まれる最小スコア。", "nullable": true }, "weights": { "type": "number", "format": "float", "description": "ハイブリッド検索モードでのセマンティック検索の重み。", "nullable": true } } }, "PreprocessingRule": { "type": "object", "description": "ドキュメントコンテンツの前処理ルール。", "properties": { "id": { "type": "string", "description": "前処理ルールの一意識別子。", "enum": [ "remove_extra_spaces", "remove_urls_emails" ] }, "enabled": { "type": "boolean", "description": "このルールが有効かどうか。" } } }, "SegmentationRule": { "type": "object", "description": "ドキュメントコンテンツをチャンクにセグメント化するためのルール。", "properties": { "separator": { "type": "string", "description": "セグメントを分離するために使用するカスタム区切り文字。" }, "max_tokens": { "type": "integer", "description": "単一セグメントで許可される最大トークン数。" } } }, "SubChunkSegmentationRule": { "type": "object", "description": "親チャンクを小さな子チャンクにセグメント化するためのルール（階層モード用）。", "properties": { "separator": { "type": "string", "description": "サブチャンク化の区切り文字。" }, "max_tokens": { "type": "integer", "description": "サブチャンクの最大トークン長。" }, "chunk_overlap": { "type": "integer", "description": "隣接するサブチャンク間の重複トークン数。" } } }, "ProcessRule": { "type": "object", "description": "クリーニングとセグメント化を含む、ドキュメントを処理するためのルールセット。", "properties": { "mode": { "type": "string", "description": "処理モード：automatic、custom、またはhierarchical。", "enum": [ "automatic", "custom", "hierarchical" ] }, "rules": { "type": "object", "description": "適用する特定のルール、モードが'custom'または'hierarchical'の場合に使用。", "properties": { "pre_processing_rules": { "type": "array", "items": { "$ref": "#/components/schemas/PreprocessingRule" } }, "segmentation": { "$ref": "#/components/schemas/SegmentationRule" }, "parent_mode": { "type": "string", "description": "階層モードでの親チャンクの取得モード。", "enum": [ "full-doc", "paragraph" ] }, "subchunk_segmentation": { "$ref": "#/components/schemas/SubChunkSegmentationRule" } }, "nullable": true } } }, "CreateDocumentByTextRequest": { "type": "object", "required": [ "name", "text" ], "properties": { "name": { "type": "string", "description": "ドキュメントの名前。" }, "text": { "type": "string", "description": "ドキュメントの完全なテキストコンテンツ。" }, "indexing_technique": { "type": "string", "description": "ドキュメントのインデックス化技術。", "enum": [ "high_quality", "economy" ] }, "doc_form": { "type": "string", "description": "インデックス化されたコンテンツの形式。", "enum": [ "text_model", "hierarchical_model", "qa_model" ] }, "doc_language": { "type": "string", "description": "ドキュメントの言語、Q&Aモードで重要。", "example": "Japanese" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "embedding_model": { "type": "string", "description": "使用する埋め込みモデルの名前。" }, "embedding_model_provider": { "type": "string", "description": "埋め込みモデルのプロバイダー。" } } }, "CreateDocumentByFileRequestData": { "type": "object", "description": "ファイルからドキュメントを作成するためのメタデータとルール。", "properties": { "original_document_id": { "type": "string", "description": "再アップロードまたは修正する既存のドキュメントのID。", "format": "uuid" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ] }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ] }, "doc_language": { "type": "string", "example": "Japanese" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "embedding_model": { "type": "string" }, "embedding_model_provider": { "type": "string" } } }, "UpdateDocumentByTextRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "ドキュメントの新しい名前（オプション）。" }, "text": { "type": "string", "description": "ドキュメントの新しいテキストコンテンツ（オプション）。" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" } } }, "UpdateDocumentByFileRequestData": { "type": "object", "properties": { "name": { "type": "string", "description": "ドキュメントの新しい名前（オプション）。" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "data_source_type": { "type": "string" }, "data_source_info": { "type": "object", "nullable": true }, "dataset_process_rule_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "created_from": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer" }, "indexing_status": { "type": "string" }, "error": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disabled_at": { "type": "integer", "format": "int64", "nullable": true }, "disabled_by": { "type": "string", "format": "uuid", "nullable": true }, "archived": { "type": "boolean" }, "display_status": { "type": "string" }, "word_count": { "type": "integer" }, "hit_count": { "type": "integer" }, "doc_form": { "type": "string" } } }, "DocumentCreationResponse": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "インデックス化の進捗を追跡するためのバッチ識別子。" } } }, "CreateDatasetRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "ナレッジベースの名前。" }, "description": { "type": "string", "description": "ナレッジベースの説明（オプション）。" }, "indexing_technique": { "type": "string", "description": "使用するインデックス化技術。", "enum": [ "high_quality", "economy" ] }, "permission": { "type": "string", "description": "ナレッジベースのアクセス権限。", "enum": [ "only_me", "all_team_members", "partial_members" ] }, "provider": { "type": "string", "description": "ナレッジベースのプロバイダー。", "enum": [ "vendor", "external" ] }, "external_knowledge_api_id": { "type": "string", "description": "外部ナレッジAPIのID（プロバイダーが'external'の場合）。" }, "external_knowledge_id": { "type": "string", "description": "外部ナレッジのID（プロバイダーが'external'の場合）。" }, "embedding_model": { "type": "string", "description": "埋め込みモデルの名前。" }, "embedding_model_provider": { "type": "string", "description": "埋め込みモデルのプロバイダー。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" } } }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "provider": { "type": "string" }, "permission": { "type": "string" }, "data_source_type": { "type": "string", "nullable": true }, "indexing_technique": { "type": "string", "nullable": true }, "app_count": { "type": "integer" }, "document_count": { "type": "integer" }, "word_count": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "updated_by": { "type": "string", "format": "uuid" }, "updated_at": { "type": "integer", "format": "int64" }, "embedding_model": { "type": "string", "nullable": true }, "embedding_model_provider": { "type": "string", "nullable": true }, "embedding_available": { "type": "boolean", "nullable": true } } }, "DatasetListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, "DatasetDetail": { "allOf": [ { "$ref": "#/components/schemas/Dataset" }, { "type": "object", "properties": { "retrieval_model_dict": { "$ref": "#/components/schemas/RetrievalModel" }, "tags": { "type": "array", "items": { "type": "object" } }, "doc_form": { "type": "string", "nullable": true } } } ] }, "UpdateDatasetRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "ナレッジベースの新しい名前。" }, "description": { "type": "string", "description": "ナレッジベースの新しい説明。" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ] }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ] }, "embedding_model_provider": { "type": "string" }, "embedding_model": { "type": "string" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "partial_member_list": { "type": "array", "description": "'partial_members'権限のメンバーIDリスト。", "items": { "type": "string" } } } }, "IndexingStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "indexing_status": { "type": "string" }, "processing_started_at": { "type": "number", "format": "float" }, "parsing_completed_at": { "type": "number", "format": "float" }, "cleaning_completed_at": { "type": "number", "format": "float" }, "splitting_completed_at": { "type": "number", "format": "float" }, "completed_at": { "type": "number", "format": "float", "nullable": true }, "paused_at": { "type": "number", "format": "float", "nullable": true }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "number", "format": "float", "nullable": true }, "completed_segments": { "type": "integer" }, "total_segments": { "type": "integer" } } }, "DocumentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, "DocumentDetail": { "allOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "object", "properties": { "dataset_process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "document_process_rule": { "allOf": [ { "$ref": "#/components/schemas/ProcessRule" }, { "type": "object", "properties": { "id": { "type": "string" }, "dataset_id": { "type": "string" } } } ] }, "indexing_latency": { "type": "number", "format": "float", "nullable": true }, "segment_count": { "type": "integer" }, "average_segment_length": { "type": "integer" }, "doc_language": { "type": "string", "nullable": true } } } ] }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "document_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "answer": { "type": "string", "nullable": true }, "word_count": { "type": "integer" }, "tokens": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } }, "index_node_id": { "type": "string" }, "index_node_hash": { "type": "string" }, "hit_count": { "type": "integer" }, "enabled": { "type": "boolean" }, "disabled_at": { "type": "integer", "format": "int64", "nullable": true }, "disabled_by": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "indexing_at": { "type": "integer", "format": "int64" }, "completed_at": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "integer", "format": "int64", "nullable": true } } }, "CreateSegmentsRequest": { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "チャンクのテキストコンテンツ（Q&Aモードでは質問）。" }, "answer": { "type": "string", "description": "回答コンテンツ、ドキュメントがQ&Aモードの場合は必須。" }, "keywords": { "type": "array", "description": "チャンクに関連付けられたキーワード。", "items": { "type": "string" } } } } } } }, "SegmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "doc_form": { "type": "string" } } }, "SegmentPaginatedResponse": { "allOf": [ { "$ref": "#/components/schemas/SegmentListResponse" }, { "type": "object", "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } } ] }, "SegmentDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string" } } }, "UpdateSegmentRequest": { "type": "object", "properties": { "segment": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "answer": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "regenerate_child_chunks": { "type": "boolean", "description": "子チャンクを再生成するかどうか（階層モード）。" } } } } }, "RetrieveRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "検索クエリ文字列。" }, "retrieval_model": { "allOf": [ { "$ref": "#/components/schemas/RetrievalModel" }, { "type": "object", "properties": { "metadata_filtering_conditions": { "type": "object", "description": "メタデータに基づいて結果をフィルタする条件。", "properties": { "logical_operator": { "type": "string", "enum": [ "and", "or" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "メタデータフィールドの名前。" }, "comparison_operator": { "type": "string", "description": "比較の演算子。" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true, "description": "比較する値。" } } } } } } } } ] } } }, "RetrievedSegment": { "type": "object", "properties": { "segment": { "allOf": [ { "$ref": "#/components/schemas/Segment" }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "data_source_type": { "type": "string" }, "name": { "type": "string" } } } } } ] }, "score": { "type": "number", "format": "float" } } }, "RetrieveResponse": { "type": "object", "properties": { "query": { "type": "object", "properties": { "content": { "type": "string" } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievedSegment" } } } }, "Model": { "type": "object", "properties": { "model": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } }, "model_type": { "type": "string" }, "features": { "type": "array", "items": {}, "nullable": true }, "fetch_from": { "type": "string" }, "model_properties": { "type": "object", "properties": { "context_size": { "type": "integer" } } }, "deprecated": { "type": "boolean" }, "status": { "type": "string" }, "load_balancing_enabled": { "type": "boolean" } } }, "ModelProvider": { "type": "object", "properties": { "provider": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } }, "icon_small": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "icon_large": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "status": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "ChildChunk": { "type": "object", "description": "階層セグメント化における子チャンクを表します。", "properties": { "id": { "type": "string", "format": "uuid" }, "segment_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "word_count": { "type": "integer" }, "tokens": { "type": "integer" }, "index_node_id": { "type": "string" }, "index_node_hash": { "type": "string" }, "status": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "indexing_at": { "type": "integer", "format": "int64" }, "completed_at": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "integer", "format": "int64", "nullable": true } } }, "CreateChildChunkRequest": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "子チャンクのコンテンツ。" } } }, "UpdateChildChunkRequest": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "子チャンクの更新されたコンテンツ。" } } }, "ChildChunkResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "ChildChunkListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChildChunk" } }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "UploadFileResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "ファイルのプレビューURL。" }, "download_url": { "type": "string", "format": "uri", "description": "ファイルのダウンロードURL。" }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "example": "knowledge" }, "binding_count": { "type": "integer" } } } } } }