langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-22 20:36:31 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
6258bbfb0f653f3caaa06fae84207c82041b0ac8
dify-docs/ja/api-reference/openapi_knowledge.json
T
Riskey 32e1b169da feat: consolidate and restructure the API reference (Phase 1) (#846) 
* docs: correct HITL API integration flow and sync translations

- Fix the claim that the resume endpoint differs per app type (same
  endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
  (chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
  returns 404); add include_state_snapshot and continue_on_pause
  guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page

* fix: correct API references against verified backend behavior

Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.

- Add curl samples for GET endpoints with required query params
  (Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
  string; DELETE /conversations requires a JSON body; audio-to-text
  accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
  created_by_account filters by email; triggered_from values are
  app-run/webhook/schedule/plugin; stop endpoints' user semantics
  differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
  403, file preview endpoint in the workflow spec, invented
  score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
  response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
  values, no response-field enums)

* fix: complete API reference audit for knowledge and completion specs

* feat: add API spec consolidation pipeline

Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.

* feat: consolidate API reference into one spec per language

Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.

* fix: remove dead conversation_completed error from chat specs

ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.

* feat: add membership matrix and restructure nav config

* feat: rename resource tags and update all references

* feat: stamp per-operation availability lines

* feat: wire three-group API navigation

* feat: add app-type page coverage lint

* docs: rewrite chatflow overview as app-type API guide

* docs: polish chatflow overview zh and ja wording

* docs: rewrite workflow overview as app-type API guide

* docs: align workflow overview details across languages

* docs: expand new agent overview into app-type API guide

* docs: use task-oriented heading on new agent overview

* docs: rewrite chatbot and agent overview as app-type API guide

* docs: rewrite text generator overview as app-type API guide

* docs: match end user link text to merged spec summary

* docs: rewrite knowledge overview as app-type API guide

* docs: move knowledge api guide into api reference

* docs: localize ui labels on knowledge overview

* docs: refresh pipeline readme for restructure modes

* docs: name app-type pages in the guides sidebar

* feat: rename zh completion messages tag to match resource framing

* docs: prototype endpoints-first layout on chatflow overview

* docs: correct detail accuracy on chatflow overview

* docs: move human input flow guide into api reference

Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.

* fix: update spec links to the moved human input guide

* fix: let spec lint accept mdx guide pages under api-reference

* docs: align chatflow zh and ja overviews to endpoints-first layout

* docs: polish chatflow zh and ja mode terms and hitl wording

* docs: align workflow overviews to endpoints-first layout

* docs: document form expiry path in human input flow guide

* docs: align new agent overviews to endpoints-first layout

* docs: align chatbot and agent overviews to endpoints-first layout

* docs: align text generator overviews to endpoints-first layout

* docs: align knowledge overviews to endpoints-first layout

* docs: correct built-in metadata examples and agent heading

* docs: flatten app-type pages directly under guides

* docs: make guide pages self-contained and trim reference detail

* docs: add get started guide and retire developing-with-apis

* docs: update new agent api behavior for latest main

New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.

* docs: audit fixes for get started and human input flow guides

* docs: fix em dash spacing and ja sentence length in get started

* docs: move message_end note to the send endpoint line

* docs: update writing guides and API skill for app-type naming

- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.

* feat: add operation sidebar titles and simplify API redirects

- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).

* docs: correct app-type naming and translations across API specs

- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.

* docs: add streaming, errors, and end-user identity API guides

- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.

* docs: reconcile API guides and apply app-type naming

- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.

* feat: wire API nav and redirects for consolidated guides

- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.

* fix: normalize zh model-provider term to 模型供应商

Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.

* docs: use Info callouts for guide forward-link notes

Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.

* refactor: remove one-time analyze mode and verification compose

- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.

* fix: correct Chatflow naming and reasoning wording in SSE overrides

- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".

* docs: refine API guide wording and simplify the human-input example

* docs: standardize Workflow and Chatflow app-type capitalization

Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.

* fix: use 供应商 for model provider in the zh Knowledge spec

* fix: rename the Knowledge API nav group to "Knowledge APIs"

* fix: un-deprecate Update Document by Text in the Knowledge spec

* translate: un-deprecate Update Document by Text in zh/ja specs

Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
2026-07-09 16:40:54 +08:00

8589 lines
347 KiB
JSON
Raw Blame History

{
"openapi": "3.0.1",
"info": {
"title": "ナレッジAPI",
"description": "ナレッジベース、ドキュメント、チャンク、メタデータ、タグの管理（作成、取得、設定を含む）のための API です。**注意：**単一のナレッジベース API キーは、同じアカウント配下のすべての可視ナレッジベースを操作する権限を持ちます。データセキュリティにご注意ください。",
"version": "1.0.0"
},
"servers": [
{
"url": "https://{api_base_url}",
"description": "Knowledge API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。",
"variables": {
"api_base_url": {
"default": "api.dify.ai/v1",
"description": "API ベース URL のホストとパス（`https://` を除く）。"
}
}
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"tags": [
{
"name": "ナレッジベース",
"description": "ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。"
},
{
"name": "ドキュメント",
"description": "ナレッジベース内のドキュメントの作成、更新、管理のための操作です。"
},
{
"name": "チャンク",
"description": "ドキュメントチャンクと子チャンクの管理のための操作です。"
},
{
"name": "メタデータ",
"description": "ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。"
},
{
"name": "タグ管理",
"description": "ナレッジベースタグとタグバインディングの管理のための操作です。"
},
{
"name": "モデル",
"description": "利用可能なモデルを取得するための操作です。"
},
{
"name": "ナレッジパイプライン",
"description": "データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。"
}
],
"paths": {
"/datasets": {
"post": {
"tags": [
"ナレッジベース"
],
"summary": "空のナレッジベースを作成",
"description": "新しい空のナレッジベースを作成します。作成後、[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) または [ファイルからドキュメントを作成](/api-reference/ドキュメント/ファイルからドキュメントを作成) を使用してドキュメントを追加します。",
"operationId": "createDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "ナレッジベース名。"
},
"description": {
"type": "string",
"maxLength": 400,
"default": "",
"description": "ナレッジベースの説明です。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"nullable": true,
"description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。"
},
"permission": {
"type": "string",
"enum": [
"only_me",
"all_team_members",
"partial_members"
],
"default": "only_me",
"description": "このナレッジベースにアクセスできるユーザーを制御します。`only_me` は作成者のみに制限、`all_team_members` はワークスペース全体にアクセスを許可、`partial_members` は指定されたメンバーにアクセスを許可します。"
},
"provider": {
"type": "string",
"enum": [
"vendor",
"external"
],
"default": "vendor",
"description": "`vendor` は内部ナレッジベース、`external` は外部ナレッジベースです。"
},
"embedding_model": {
"type": "string",
"description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。"
},
"embedding_model_provider": {
"type": "string",
"description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部ナレッジ API 接続の ID です。"
},
"external_knowledge_id": {
"type": "string",
"description": "外部ナレッジベースの ID です。"
},
"summary_index_setting": {
"type": "object",
"nullable": true,
"description": "サマリーインデックスの設定です。",
"properties": {
"enable": {
"type": "boolean",
"description": "サマリーインデックスを有効にするかどうかです。"
},
"model_name": {
"type": "string",
"description": "要約生成に使用されるモデルの名前です。"
},
"model_provider_name": {
"type": "string",
"description": "要約生成モデルのプロバイダーです。"
},
"summary_prompt": {
"type": "string",
"description": "要約生成用のカスタムプロンプトテンプレートです。"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "ナレッジベースが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "プロダクト API 技術ドキュメント",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"409": {
"description": "`dataset_name_duplicate` : ナレッジベース名は既に存在します。名前を変更してください。",
"content": {
"application/json": {
"examples": {
"dataset_name_duplicate": {
"summary": "dataset_name_duplicate",
"value": {
"status": 409,
"code": "dataset_name_duplicate",
"message": "The dataset name already exists. Please modify your dataset name."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"ナレッジベース"
],
"summary": "ナレッジベースリストを取得",
"description": "ナレッジベースのページネーションリストを返します。キーワードとタグによるフィルタリングをサポートしています。",
"operationId": "listDatasets",
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "取得するページ番号。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "1 ページあたりの件数です。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "名前でフィルタリングする検索キーワードです。"
},
{
"name": "include_all",
"in": "query",
"schema": {
"type": "boolean",
"default": false
},
"description": "権限に関係なくすべてのナレッジベースを含めるかどうかです。"
},
{
"name": "tag_ids",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "フィルタリングに使用するタグ ID です。"
}
],
"responses": {
"200": {
"description": "ナレッジベースのリストです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "ナレッジベースオブジェクトの配列です。",
"items": {
"$ref": "#/components/schemas/Dataset"
}
},
"has_more": {
"type": "boolean",
"description": "次のページにさらに項目が存在するかどうかです。"
},
"limit": {
"type": "integer",
"description": "1 ページあたりの件数です。"
},
"total": {
"type": "integer",
"description": "一致する項目の合計数です。"
},
"page": {
"type": "integer",
"description": "現在のページ番号です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "プロダクト API 技術ドキュメント",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}": {
"get": {
"tags": [
"ナレッジベース"
],
"summary": "ナレッジベース詳細を取得",
"description": "特定のナレッジベースの詳細情報（埋め込みモデル、検索設定、ドキュメント統計を含む）を取得します。",
"operationId": "getDatasetDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"responses": {
"200": {
"description": "ナレッジベースの詳細です。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "プロダクト API 技術ドキュメント",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"patch": {
"tags": [
"ナレッジベース"
],
"summary": "ナレッジベースを更新",
"description": "既存のナレッジベースの名前、説明、権限、または検索設定を更新します。リクエストボディで指定されたフィールドのみが更新されます。",
"operationId": "updateDataset",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "ナレッジベース名。"
},
"description": {
"type": "string",
"maxLength": 400,
"description": "ナレッジベースの説明です。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"nullable": true,
"description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。"
},
"permission": {
"type": "string",
"enum": [
"only_me",
"all_team_members",
"partial_members"
],
"description": "このナレッジベースにアクセスできるユーザーを制御します。`only_me` は作成者のみに制限、`all_team_members` はワークスペース全体にアクセスを許可、`partial_members` は指定されたメンバーにアクセスを許可します。"
},
"embedding_model": {
"type": "string",
"description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。"
},
"embedding_model_provider": {
"type": "string",
"description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。"
},
"partial_member_list": {
"type": "array",
"description": "`permission` が `partial_members` の場合にアクセス権を持つチームメンバーのリストです。",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "アクセス権を付与するチームメンバーの ID です。"
}
}
}
},
"external_retrieval_model": {
"type": "object",
"description": "外部ナレッジベースの検索設定です。",
"properties": {
"top_k": {
"type": "integer",
"description": "返す結果の最大数です。"
},
"score_threshold": {
"type": "number",
"description": "結果フィルタリング用の最小関連性スコア閾値です。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "スコア閾値フィルタリングが有効かどうかです。"
}
}
},
"external_knowledge_id": {
"type": "string",
"description": "外部ナレッジベースの ID です。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部ナレッジ API 接続の ID です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ナレッジベースが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "プロダクト API 技術ドキュメント",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin",
"partial_member_list": []
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"ナレッジベース"
],
"summary": "ナレッジベースを削除",
"description": "ナレッジベースとそのすべてのドキュメントを完全に削除します。",
"operationId": "deleteDataset",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/document/create-by-text": {
"post": {
"tags": [
"ドキュメント"
],
"summary": "テキストからドキュメントを作成",
"description": "テキストコンテンツからドキュメントを作成します。ドキュメントは非同期で処理されるため、返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。",
"operationId": "createDocumentFromText",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"text"
],
"properties": {
"name": {
"type": "string",
"description": "ドキュメント名です。"
},
"text": {
"type": "string",
"description": "ドキュメントのテキスト内容です。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"description": "ナレッジベースに最初のドキュメントを追加する際に必須です。以降のドキュメントでは省略するとナレッジベースのインデックス方式を継承します。`high_quality` は埋め込みモデルによる精密検索、`economy` はキーワードベースのインデックスを使用します。"
},
"doc_form": {
"type": "string",
"enum": [
"text_model",
"hierarchical_model",
"qa_model"
],
"default": "text_model",
"description": "`text_model` は標準テキストチャンキング、`hierarchical_model` は親子チャンク構造、`qa_model` は質問・回答ペアの抽出です。"
},
"doc_language": {
"type": "string",
"default": "English",
"description": "処理最適化のためのドキュメント言語です。"
},
"process_rule": {
"type": "object",
"description": "チャンキングの処理ルールです。",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"automatic",
"custom",
"hierarchical"
],
"description": "処理モードです。`automatic` は組み込みルールを使用、`custom` は手動設定が可能、`hierarchical` は親子チャンク構造を有効にします（`doc_form: hierarchical_model` と組み合わせて使用）。"
},
"rules": {
"type": "object",
"properties": {
"pre_processing_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"remove_stopwords",
"remove_extra_spaces",
"remove_urls_emails"
],
"description": "ルール識別子です。"
},
"enabled": {
"type": "boolean",
"description": "この前処理ルールが有効かどうかです。"
}
}
}
},
"segmentation": {
"type": "object",
"properties": {
"separator": {
"type": "string",
"default": "\n",
"description": "テキスト分割用のカスタムセパレーターです。"
},
"max_tokens": {
"type": "integer",
"description": "チャンクあたりの最大トークン数です。"
},
"chunk_overlap": {
"type": "integer",
"default": 0,
"description": "チャンク間のトークンオーバーラップです。"
}
}
}
}
}
}
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。"
},
"embedding_model": {
"type": "string",
"description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。"
},
"embedding_model_provider": {
"type": "string",
"description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。"
},
"original_document_id": {
"type": "string",
"description": "バージョン管理用の元ドキュメント ID です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "インデックス進捗を追跡するためのバッチ ID です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 0,
"indexing_status": "indexing",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "indexing",
"word_count": 0,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : 最初のドキュメント追加時には `indexing_technique` が必須です。または `doc_form` が無効です。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_indexing": {
"summary": "invalid_param (indexing_technique)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "indexing_technique is required."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : ドキュメント数がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (documents limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The number of documents has reached the limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/document/create-by-file": {
"post": {
"tags": [
"ドキュメント"
],
"summary": "ファイルからドキュメントを作成",
"description": "ファイルをアップロードしてドキュメントを作成します。一般的なドキュメント形式（PDF、TXT、DOCX など）をサポートしています。処理は非同期で行われるため、返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。",
"operationId": "createDocumentFromFile",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "アップロードするファイルです。"
},
"data": {
"type": "string",
"description": "設定情報を含む JSON 文字列です。[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) と同じフィールド（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`）を受け付けますが、`name` と `text` は除きます。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "インデックス進捗を追跡するためのバッチ ID です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 0,
"indexing_status": "indexing",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "indexing",
"word_count": 0,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `no_file_uploaded` : ファイルをアップロードしてください。\n- `too_many_files` : アップロードできるファイルは 1 つだけです。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : 外部ナレッジベースはサポートされていません。`indexing_technique` が必須、または `process_rule` がありません。",
"content": {
"application/json": {
"examples": {
"no_file_uploaded": {
"summary": "no_file_uploaded",
"value": {
"status": 400,
"code": "no_file_uploaded",
"message": "Please upload your file."
}
},
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_external": {
"summary": "invalid_param (external)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "External datasets are not supported."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : ドキュメント数がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (documents limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The number of documents has reached the limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents": {
"get": {
"tags": [
"ドキュメント"
],
"summary": "ナレッジベースのドキュメントリストを取得",
"description": "ナレッジベース内のドキュメントのページネーションされた一覧を返します。キーワードやインデックスステータスによるフィルタリングをサポートしています。",
"operationId": "listDocuments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "取得するページ番号。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "1 ページあたりの項目数です。サーバーの上限は `100` です。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "ドキュメント名でフィルタリングするための検索キーワードです。"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"queuing",
"indexing",
"paused",
"error",
"available",
"disabled",
"archived"
]
},
"description": "表示ステータスでフィルタリングします。"
}
],
"responses": {
"200": {
"description": "ドキュメントのリストです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "ドキュメントオブジェクトの配列です。",
"items": {
"$ref": "#/components/schemas/Document"
}
},
"has_more": {
"type": "boolean",
"description": "次のページにさらに項目が存在するかどうかです。"
},
"limit": {
"type": "integer",
"description": "1 ページあたりの件数です。"
},
"total": {
"type": "integer",
"description": "一致する項目の合計数です。"
},
"page": {
"type": "integer",
"description": "現在のページ番号です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}": {
"get": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメント詳細を取得",
"description": "特定のドキュメントの詳細情報（インデックスステータス、メタデータ、処理統計を含む）を取得します。",
"operationId": "getDocumentDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "metadata",
"in": "query",
"schema": {
"type": "string",
"enum": [
"all",
"only",
"without"
],
"default": "all"
},
"description": "`all` はメタデータを含むすべてのフィールドを返します。`only` は `id`、`doc_type`、`doc_metadata` のみを返します。`without` は `doc_metadata` を除くすべてのフィールドを返します。"
}
],
"responses": {
"200": {
"description": "ドキュメントの詳細です。レスポンスの形式は `metadata` クエリパラメータによって異なります。`metadata` が `only` の場合、`id`、`doc_type`、`doc_metadata` のみが返されます。`metadata` が `without` の場合、`doc_type` と `doc_metadata` は省略されます。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ドキュメント識別子です。"
},
"position": {
"type": "integer",
"description": "ナレッジベース内の位置インデックスです。"
},
"data_source_type": {
"type": "string",
"description": "ドキュメントのアップロード方法です。ファイルアップロードの場合は `upload_file`、Notion インポートの場合は `notion_import` です。"
},
"data_source_info": {
"type": "object",
"description": "データソースの詳細です。ファイルアップロードの場合、この詳細エンドポイントは `upload_file` 配下に完全なファイルオブジェクトを返します（リストエンドポイントは `upload_file_id` のみを返します）。",
"properties": {
"upload_file": {
"type": "object",
"description": "アップロードされたファイルの詳細です。`data_source_type` が `upload_file` の場合に返されます。",
"properties": {
"id": {
"type": "string",
"description": "ファイル識別子です。"
},
"name": {
"type": "string",
"description": "元のファイル名です。"
},
"size": {
"type": "integer",
"description": "ファイルサイズ（バイト単位）です。"
},
"extension": {
"type": "string",
"description": "ファイル拡張子です。"
},
"mime_type": {
"type": "string",
"description": "ファイルの MIME タイプです。"
},
"created_by": {
"type": "string",
"description": "ファイルをアップロードしたユーザーの ID です。"
},
"created_at": {
"type": "integer",
"description": "ファイルアップロードの Unix タイムスタンプです。"
}
}
}
}
},
"dataset_process_rule_id": {
"type": "string",
"description": "このドキュメントに適用された処理ルールの ID です。"
},
"dataset_process_rule": {
"type": "object",
"description": "ナレッジベースレベルの処理ルール設定です。"
},
"document_process_rule": {
"type": "object",
"description": "ドキュメントレベルの処理ルール設定です。"
},
"name": {
"type": "string",
"description": "ドキュメント名です。"
},
"created_from": {
"type": "string",
"description": "ドキュメントの作成元です。API で作成した場合は `api`、UI で作成した場合は `web` です。"
},
"created_by": {
"type": "string",
"description": "ドキュメントを作成したユーザーの ID です。"
},
"created_at": {
"type": "number",
"description": "ドキュメント作成の Unix タイムスタンプです。"
},
"tokens": {
"type": "integer",
"description": "ドキュメント内のトークン数です。"
},
"indexing_status": {
"type": "string",
"description": "現在のインデックスステータスです（例：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`）。"
},
"error": {
"type": "string",
"nullable": true,
"description": "インデックス作成が失敗した場合のエラーメッセージです。それ以外は `null` です。"
},
"enabled": {
"type": "boolean",
"description": "このドキュメントが検索に対して有効かどうかです。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "ドキュメントが無効化された Unix タイムスタンプです。有効な場合は `null` です。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "ドキュメントを無効化したユーザーの ID です。有効な場合は `null` です。"
},
"archived": {
"type": "boolean",
"description": "ドキュメントがアーカイブ済みかどうかです。"
},
"display_status": {
"type": "string",
"description": "UI 向けの表示用インデックスステータスです。"
},
"hit_count": {
"type": "integer",
"description": "このドキュメントが検索された回数です。"
},
"doc_form": {
"type": "string",
"description": "ドキュメントのチャンキングモードです。`text_model` は標準テキスト、`hierarchical_model` は親子構造、`qa_model` は QA ペアを示します。"
},
"doc_language": {
"type": "string",
"description": "ドキュメント内容の言語です。"
},
"doc_type": {
"type": "string",
"nullable": true,
"description": "ドキュメントタイプの分類です。未設定の場合は `null` です。"
},
"doc_metadata": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの種類です。"
},
"value": {
"type": "string",
"description": "このドキュメントのメタデータフィールド値。"
}
}
},
"description": "このドキュメントのカスタムメタデータキーバリューペア。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "処理が完了した Unix タイムスタンプです。まだ完了していない場合は `null` です。"
},
"updated_at": {
"type": "number",
"nullable": true,
"description": "最終更新の Unix タイムスタンプです。更新されたことがない場合は `null` です。"
},
"indexing_latency": {
"type": "number",
"nullable": true,
"description": "インデックス作成にかかった時間（秒）です。未完了の場合は `null` です。"
},
"segment_count": {
"type": "integer",
"description": "ドキュメント内のチャンク数です。"
},
"average_segment_length": {
"type": "number",
"description": "チャンクの平均文字長です。"
},
"summary_index_status": {
"type": "string",
"nullable": true,
"description": "要約インデックスのステータスです。要約インデックスが有効でない場合は `null` です。"
},
"need_summary": {
"type": "boolean",
"description": "このドキュメントが要約生成を必要とするかどうかです。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"dataset_process_rule": {
"id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"mode": "custom"
},
"document_process_rule": {
"mode": "custom",
"rules": {
"pre_processing_rules": [],
"segmentation": {
"separator": "###",
"max_tokens": 500,
"chunk_overlap": 50
}
}
},
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"hit_count": 0,
"doc_form": "text_model",
"doc_language": "English",
"doc_type": null,
"doc_metadata": [],
"completed_at": 1741267260,
"updated_at": 1741267260,
"indexing_latency": 60.0,
"segment_count": 5,
"average_segment_length": 70.0,
"summary_index_status": null,
"need_summary": false
}
}
}
}
}
},
"400": {
"description": "`invalid_metadata` : `metadata` クエリパラメータの値が無効です（`all`、`only`、`without` のいずれかである必要があります）。",
"content": {
"application/json": {
"examples": {
"invalid_metadata": {
"summary": "invalid_metadata",
"value": {
"status": 400,
"code": "invalid_metadata",
"message": "Invalid metadata value: only"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 権限がありません。\n- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (no permission)",
"value": {
"status": 403,
"code": "forbidden",
"message": "No permission."
}
},
"forbidden_2": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメントを削除",
"description": "ナレッジベースからドキュメントとそのすべてのチャンクを完全に削除します。",
"operationId": "deleteDocument",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `archived_document_immutable` : アーカイブされたドキュメントは編集できません。\n- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"archived_document_immutable": {
"summary": "archived_document_immutable",
"value": {
"status": 403,
"code": "archived_document_immutable",
"message": "The archived document is not editable."
}
},
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ドキュメントが存在しません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document Not Exists."
}
}
}
}
}
}
}
},
"patch": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメントを更新",
"description": "新しいファイルをアップロードして既存のドキュメントを更新します。これはファイルベースのドキュメント更新の正規エンドポイントです。インデックスが再トリガーされるため、返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。",
"operationId": "updateDocument",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "アップロードするファイルです。"
},
"data": {
"type": "string",
"description": "設定情報を含む JSON 文字列です。[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) と同じフィールド（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`）を受け付けますが、`name` と `text` は除きます。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "インデックス進捗を追跡するためのバッチ ID です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : ドキュメントが更新できる状態ではありません（利用可能なドキュメントのみ更新できます）。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : ファイルサイズが上限を超えています。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 許可されていないファイルタイプです。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/download": {
"get": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメントをダウンロード",
"description": "ドキュメントの元のアップロードファイルの署名付きダウンロード URL を取得します。",
"operationId": "downloadDocumentJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"responses": {
"200": {
"description": "ダウンロード URL が正常に生成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "元のアップロードファイルをダウンロードするための署名付き URL です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 権限がありません。\n- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (no permission)",
"value": {
"status": 403,
"code": "forbidden",
"message": "No permission."
}
},
"forbidden_2": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{batch}/indexing-status": {
"get": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメント埋め込みステータス（進捗）を取得",
"description": "バッチ内のドキュメントのインデックス進捗を確認します。各ドキュメントの現在の処理段階とチャンク完了数を返します。`indexing_status` が `completed` または `error` に達するまでこのエンドポイントをポーリングしてください。ステータスは次の順序で進行します：`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。",
"operationId": "getDocumentIndexingStatus",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "batch",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "ドキュメント作成時に返されるバッチ ID です。"
}
],
"responses": {
"200": {
"description": "バッチ内のドキュメントのインデックス状態です。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ドキュメント識別子です。"
},
"indexing_status": {
"type": "string",
"description": "現在のインデックスステータスです：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、または `error`。"
},
"processing_started_at": {
"type": "number",
"description": "処理開始時の Unix タイムスタンプです。"
},
"parsing_completed_at": {
"type": "number",
"description": "パース完了時の Unix タイムスタンプです。"
},
"cleaning_completed_at": {
"type": "number",
"description": "クリーニング完了時の Unix タイムスタンプです。"
},
"splitting_completed_at": {
"type": "number",
"description": "分割完了時の Unix タイムスタンプです。"
},
"completed_at": {
"type": "number",
"description": "インデックス完了時の Unix タイムスタンプです。"
},
"paused_at": {
"type": "number",
"nullable": true,
"description": "インデキシングが一時停止されたタイムスタンプ。一時停止されていない場合は `null`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "インデキシングが失敗した場合のエラーメッセージ。エラーがない場合は `null`。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "インデキシングが停止されたタイムスタンプ。停止されていない場合は `null`。"
},
"completed_segments": {
"type": "integer",
"description": "インデックス済みのチャンク数です。"
},
"total_segments": {
"type": "integer",
"description": "インデックス対象のチャンクの合計数です。"
}
}
},
"description": "インデキシングステータスエントリのリスト。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"indexing_status": "completed",
"processing_started_at": 1741267200,
"parsing_completed_at": 1741267200,
"cleaning_completed_at": 1741267200,
"splitting_completed_at": 1741267200,
"completed_at": 1741267200,
"paused_at": null,
"error": null,
"stopped_at": null,
"completed_segments": 5,
"total_segments": 5
}
]
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。/ ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"dataset_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"documents_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Documents not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/update-by-text": {
"post": {
"tags": [
"ドキュメント"
],
"summary": "テキストでドキュメントを更新",
"description": "既存のドキュメントのテキスト内容、名前、または処理設定を更新します。内容が変更されると、インデックスを再トリガーします。",
"operationId": "updateDocumentByText",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "ドキュメント名です。`text` を指定する場合は必須です。"
},
"text": {
"type": "string",
"description": "ドキュメントのテキスト内容です。"
},
"process_rule": {
"type": "object",
"description": "チャンキングの処理ルールです。",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"automatic",
"custom",
"hierarchical"
],
"description": "処理モードです。`automatic` は組み込みルールを使用、`custom` は手動設定が可能、`hierarchical` は親子チャンク構造を有効にします（`doc_form: hierarchical_model` と組み合わせて使用）。"
},
"rules": {
"type": "object",
"properties": {
"pre_processing_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"remove_stopwords",
"remove_extra_spaces",
"remove_urls_emails"
],
"description": "ルール識別子です。"
},
"enabled": {
"type": "boolean",
"description": "この前処理ルールが有効かどうかです。"
}
}
}
},
"segmentation": {
"type": "object",
"properties": {
"separator": {
"type": "string",
"default": "\n",
"description": "テキスト分割用のカスタムセパレーターです。"
},
"max_tokens": {
"type": "integer",
"description": "チャンクあたりの最大トークン数です。"
},
"chunk_overlap": {
"type": "integer",
"default": 0,
"description": "チャンク間のトークンオーバーラップです。"
}
}
}
}
}
}
},
"doc_form": {
"type": "string",
"enum": [
"text_model",
"hierarchical_model",
"qa_model"
],
"default": "text_model",
"description": "`text_model` は標準テキストチャンキング、`hierarchical_model` は親子チャンク構造、`qa_model` は質問・回答ペアの抽出です。"
},
"doc_language": {
"type": "string",
"default": "English",
"description": "処理最適化のためのドキュメント言語です。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "インデックス進捗を追跡するためのバッチ ID です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : `text` を指定する場合は `name` が必須です。または `doc_form` が無効です。\n- `invalid_param` : ドキュメントが更新できる状態ではありません（利用可能なドキュメントのみ更新できます）。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_name": {
"summary": "invalid_param (name required)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "name is required when text is provided."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/update-by-file": {
"post": {
"tags": [
"ドキュメント"
],
"summary": "ファイルでドキュメントを更新",
"description": "非推奨です。代わりに [ドキュメントを更新](/api-reference/ドキュメント/ドキュメントを更新) を使用してください。新しいファイルをアップロードして既存のドキュメントを更新し、インデックスを再トリガーします。",
"operationId": "updateDocumentByFile",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "アップロードするファイルです。"
},
"data": {
"type": "string",
"description": "設定情報を含む JSON 文字列です。[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) と同じフィールド（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`）を受け付けますが、`name` と `text` は除きます。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "インデックス進捗を追跡するためのバッチ ID です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `too_many_files` : アップロードできるファイルは 1 つだけです。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : ドキュメントが更新できる状態ではありません（利用可能なドキュメントのみ更新できます）。",
"content": {
"application/json": {
"examples": {
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : ファイルサイズが上限を超えています。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 許可されていないファイルタイプです。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
},
"deprecated": true
}
},
"/datasets/{dataset_id}/documents/download-zip": {
"post": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメントを一括ダウンロード（ZIP）",
"description": "複数のアップロードファイルドキュメントを単一の ZIP アーカイブとしてダウンロードします。最大 `100` 件のドキュメント ID を受け付けます。",
"operationId": "downloadDocumentsZipJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"document_ids"
],
"properties": {
"document_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"format": "uuid"
},
"description": "ZIP アーカイブに含めるドキュメント ID の配列です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "リクエストされたドキュメントを含む ZIP アーカイブです。",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary",
"description": "ZIP アーカイブのバイナリストリームです。"
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ドキュメントが見つかりません。\n- `not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/status/{action}": {
"patch": {
"tags": [
"ドキュメント"
],
"summary": "ドキュメントステータスを一括更新",
"description": "複数のドキュメントを一括で有効化、無効化、アーカイブ、またはアーカイブ解除します。",
"operationId": "batchUpdateDocumentStatus",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "action",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"enable",
"disable",
"archive",
"un_archive"
]
},
"description": "`enable` で有効化、`disable` で無効化、`archive` でアーカイブ、`un_archive` でアーカイブから復元します。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"document_ids"
],
"properties": {
"document_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "更新するドキュメント ID のリストです。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作結果です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"result": "success"
}
}
}
}
}
},
"400": {
"description": "`invalid_action` : アクションが無効です。またはドキュメントがアクションを許可しない状態です（インデックス中、または未完了など）。",
"content": {
"application/json": {
"examples": {
"invalid_action": {
"summary": "invalid_action",
"value": {
"status": 400,
"code": "invalid_action",
"message": "Invalid action."
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments": {
"post": {
"tags": [
"チャンク"
],
"summary": "ドキュメントにチャンクを追加",
"description": "ドキュメント内に 1 つ以上のチャンクを作成します。各チャンクには `content` が必須です。Q&A モード（`qa_model`）ドキュメントの場合は `answer` も必須です。`keywords` は任意です。",
"operationId": "createSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"segments"
],
"properties": {
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "チャンクのテキスト内容です。",
"minLength": 1
},
"answer": {
"type": "string",
"description": "QA モードの回答内容です。"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "チャンクのキーワードです。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "添付ファイル ID です。"
}
},
"required": [
"content"
]
},
"description": "作成するチャンクオブジェクトの配列です。",
"minItems": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "チャンクが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Segment"
},
"description": "作成されたチャンクのリスト。"
},
"doc_form": {
"type": "string",
"description": "このドキュメントが使用するドキュメントチャンキングモードです。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
}
],
"doc_form": "text_model"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : チャンクの検証に失敗した（内容が空など）、またはチャンク数の上限を超えました。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_limit": {
"summary": "invalid_param (segments limit)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Exceeded maximum segments limit of 1000."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : ドキュメントの処理が完了していません。\n- `not_found` : ドキュメントが無効化されています。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document is not completed."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document is disabled."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"チャンク"
],
"summary": "チャンク一覧を取得",
"description": "ドキュメント内のチャンクのページネーションリストを返します。キーワードとステータスによるフィルタリングをサポートしています。",
"operationId": "listSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "取得するページ番号。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "1 ページあたりの項目数です。サーバーの上限は `100` です。"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "インデックスステータスでチャンクをフィルタリングします（例：`completed`、`indexing`、`error`）。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "検索キーワードです。"
}
],
"responses": {
"200": {
"description": "チャンクのリストです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Segment"
},
"description": "チャンクのリスト。"
},
"doc_form": {
"type": "string",
"description": "このドキュメントが使用するドキュメントチャンキングモードです。"
},
"total": {
"type": "integer",
"description": "一致するチャンクの合計数です。"
},
"has_more": {
"type": "boolean",
"description": "次のページにさらに項目が存在するかどうかです。"
},
"limit": {
"type": "integer",
"description": "1 ページあたりの件数です。"
},
"page": {
"type": "integer",
"description": "現在のページ番号です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
}
],
"doc_form": "text_model",
"total": 1,
"has_more": false,
"limit": 20,
"page": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": {
"get": {
"tags": [
"チャンク"
],
"summary": "ドキュメント内のチャンク詳細を取得",
"description": "特定のチャンクの詳細情報（内容、キーワード、インデックスステータスを含む）を取得します。",
"operationId": "getSegmentDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"responses": {
"200": {
"description": "チャンクの詳細です。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Segment"
},
"doc_form": {
"type": "string",
"description": "このドキュメントが使用するドキュメントチャンキングモードです。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
},
"doc_form": "text_model"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"post": {
"tags": [
"チャンク"
],
"summary": "ドキュメント内のチャンクを更新",
"description": "チャンクのコンテンツ、キーワード、または回答を更新します。変更されたチャンクのインデックス作成が再トリガーされます。",
"operationId": "updateSegment",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"segment"
],
"properties": {
"segment": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "チャンクのテキスト内容です。"
},
"answer": {
"type": "string",
"description": "QA モードの回答内容です。"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "チャンクのキーワードです。"
},
"enabled": {
"type": "boolean",
"description": "チャンクが有効かどうかです。"
},
"regenerate_child_chunks": {
"type": "boolean",
"default": false,
"description": "子チャンクを再生成するかどうかです。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "添付ファイル ID です。"
},
"summary": {
"type": "string",
"nullable": true,
"description": "サマリーインデックスのサマリー内容です。"
}
},
"description": "更新するチャンクデータです。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "チャンクが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Segment"
},
"doc_form": {
"type": "string",
"description": "このドキュメントが使用するドキュメントチャンキングモードです。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
},
"doc_form": "text_model"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。Settings -> Model Provider でプロバイダーの認証情報を設定してください。\n- `invalid_param` : チャンクがインデックス中または無効化されているため更新できません。またはインデックス設定が無効です。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_state": {
"summary": "invalid_param (state)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Segment is indexing, please try again later"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"チャンク"
],
"summary": "ドキュメント内のチャンクを削除",
"description": "ドキュメントからチャンクを完全に削除します。",
"operationId": "deleteSegment",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": {
"post": {
"tags": [
"チャンク"
],
"summary": "子チャンクを作成",
"description": "親チャンクの下に子チャンクを作成します。親子（`hierarchical_model`）チャンキングモードを使用するドキュメント向けです。",
"operationId": "createChildChunk",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "子チャンクのテキスト内容です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "子チャンクが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/ChildChunk"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": {
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 子チャンクのインデックス作成に失敗しました。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Create child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"チャンク"
],
"summary": "子チャンク一覧を取得",
"description": "特定の親チャンク配下の子チャンクのページネーションリストを返します。",
"operationId": "getChildChunks",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
},
"description": "取得するページ番号。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1
},
"description": "1 ページあたりの項目数です。サーバーの上限は `100` です。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "検索キーワードです。"
}
],
"responses": {
"200": {
"description": "子チャンクのリストです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChildChunk"
},
"description": "子チャンクのリスト。"
},
"total": {
"type": "integer",
"description": "子チャンクの合計数です。"
},
"total_pages": {
"type": "integer",
"description": "合計ページ数です。"
},
"page": {
"type": "integer",
"description": "現在のページ番号です。"
},
"limit": {
"type": "integer",
"description": "1 ページあたりの件数です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
],
"total": 1,
"total_pages": 1,
"page": 1,
"limit": 20
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
}
},
"/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,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "child_chunk_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "子チャンク ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "子チャンクのテキスト内容です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "子チャンクが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/ChildChunk"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": {
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 子チャンクのインデックス更新に失敗しました。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Update child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : ベクトル空間の容量がサブスクリプションの上限に達しました。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。\n- `not_found` : 子チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Child chunk not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"チャンク"
],
"summary": "子チャンクを削除",
"description": "親チャンクから子チャンクを完全に削除します。",
"operationId": "deleteChildChunk",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Document ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "child_chunk_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "子チャンク ID です。"
}
],
"responses": {
"204": {
"description": "Success."
},
"400": {
"description": "`invalid_param` : 子チャンクのインデックス削除に失敗しました。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Delete child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : ナレッジベースが見つかりません。\n- `not_found` : ドキュメントが見つかりません。\n- `not_found` : チャンクが見つかりません。\n- `not_found` : 子チャンクが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Child chunk not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/retrieve": {
"post": {
"tags": [
"ナレッジベース"
],
"summary": "ナレッジベースからチャンクを取得 / テスト検索",
"description": "ナレッジベースに対して検索クエリを実行し、最も関連性の高いチャンクを取得します。このエンドポイントは本番環境の検索とテスト検索の両方に使用できます。",
"operationId": "retrieveSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "検索クエリテキストです。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "検索コンテキストに含める添付ファイル ID のリストです。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "検索結果です。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "object",
"description": "元のクエリオブジェクトです。",
"properties": {
"content": {
"type": "string",
"description": "クエリテキストです。"
}
}
},
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"segment": {
"type": "object",
"description": "ナレッジベースから一致したチャンクです。",
"properties": {
"id": {
"type": "string",
"description": "チャンクの一意識別子です。"
},
"position": {
"type": "integer",
"description": "ドキュメント内のチャンクの位置。"
},
"document_id": {
"type": "string",
"description": "このチャンクが属するドキュメントの ID です。"
},
"content": {
"type": "string",
"description": "チャンクのテキスト内容です。"
},
"sign_content": {
"type": "string",
"description": "整合性検証用の署名付きコンテンツハッシュです。"
},
"answer": {
"type": "string",
"description": "回答コンテンツです。Q&A モードのドキュメントで使用されます。"
},
"word_count": {
"type": "integer",
"description": "チャンク内容の単語数です。"
},
"tokens": {
"type": "integer",
"description": "チャンク内容のトークン数です。"
},
"keywords": {
"type": "array",
"description": "キーワードベースの検索のためにこのチャンクに関連付けられたキーワードです。",
"items": {
"type": "string"
}
},
"index_node_id": {
"type": "string",
"description": "ベクトルストア内のインデックスノードの ID です。"
},
"index_node_hash": {
"type": "string",
"description": "インデックスされたコンテンツのハッシュです。変更の検出に使用されます。"
},
"hit_count": {
"type": "integer",
"description": "このチャンクが検索クエリでマッチした回数です。"
},
"enabled": {
"type": "boolean",
"description": "このチャンクが検索に対して有効かどうかです。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "チャンクが無効化されたタイムスタンプです。有効な場合は `null` です。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "チャンクを無効化したユーザーの ID です。有効な場合は `null` です。"
},
"status": {
"type": "string",
"description": "チャンクのインデックスステータスです。"
},
"created_by": {
"type": "string",
"description": "チャンクを作成したユーザーの ID です。"
},
"created_at": {
"type": "number",
"description": "作成タイムスタンプ（Unix エポック、秒単位）です。"
},
"indexing_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が開始されたタイムスタンプです。まだ開始されていない場合は `null` です。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が完了したタイムスタンプです。まだ完了していない場合は `null` です。"
},
"error": {
"type": "string",
"nullable": true,
"description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が停止されたタイムスタンプです。停止されていない場合は `null` です。"
},
"document": {
"type": "object",
"description": "マッチしたチャンクの親ドキュメント情報です。",
"properties": {
"id": {
"type": "string",
"description": "ドキュメントの一意識別子です。"
},
"data_source_type": {
"type": "string",
"description": "ドキュメントの作成方法です。"
},
"name": {
"type": "string",
"description": "ドキュメント名です。"
},
"doc_type": {
"type": "string",
"nullable": true,
"description": "ドキュメントタイプの分類です。未設定の場合は `null` です。"
},
"doc_metadata": {
"type": "object",
"nullable": true,
"description": "ドキュメントのメタデータ値です。メタデータが設定されていない場合は `null` です。"
}
}
}
}
},
"child_chunks": {
"type": "array",
"description": "階層インデックスを使用している場合、チャンク内でマッチした子チャンクです。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "子チャンクの一意識別子です。"
},
"content": {
"type": "string",
"description": "子チャンクのテキスト内容です。"
},
"position": {
"type": "integer",
"description": "親チャンク内の子チャンクの位置です。"
},
"score": {
"type": "number",
"description": "子チャンクの関連性スコアです。"
}
}
}
},
"score": {
"type": "number",
"description": "関連性スコアです。"
},
"tsne_position": {
"type": "object",
"nullable": true,
"description": "t-SNE 可視化の位置です。"
},
"files": {
"type": "array",
"description": "このチャンクに添付されたファイルです。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "添付ファイルの識別子です。"
},
"name": {
"type": "string",
"description": "元のファイル名です。"
},
"size": {
"type": "integer",
"description": "ファイルサイズ（バイト）。"
},
"extension": {
"type": "string",
"description": "ファイル拡張子。"
},
"mime_type": {
"type": "string",
"description": "ファイルの MIME タイプ。"
},
"source_url": {
"type": "string",
"description": "添付ファイルにアクセスする URL です。"
}
}
}
},
"summary": {
"type": "string",
"nullable": true,
"description": "要約インデックス経由で取得された場合の要約コンテンツです。"
}
}
},
"description": "一致した検索レコードのリスト。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"query": {
"content": "What is Dify?"
},
"records": [
{
"segment": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 1,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"data_source_type": "upload_file",
"name": "guide.txt",
"doc_type": null,
"doc_metadata": null
}
},
"child_chunks": [],
"score": 0.92,
"tsne_position": null,
"files": [],
"summary": null
}
]
}
}
}
}
}
},
"400": {
"description": "- `dataset_not_initialized` : ナレッジベースはまだ初期化中またはインデキシング中です。しばらくお待ちください。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.",
"content": {
"application/json": {
"examples": {
"dataset_not_initialized": {
"summary": "dataset_not_initialized",
"value": {
"status": 400,
"code": "dataset_not_initialized",
"message": "The dataset is still being initialized or indexing. Please wait a moment."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
},
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Invalid parameter value."
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 検索中に内部エラーが発生しました。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "An internal error occurred."
}
}
}
}
}
}
}
}
},
"/datasets/tags": {
"post": {
"tags": [
"タグ管理"
],
"summary": "ナレッジベースタグを作成",
"description": "ナレッジベースを整理するための新しいタグを作成します。",
"operationId": "createKnowledgeTag",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Tag name."
}
}
}
}
}
},
"responses": {
"200": {
"description": "タグが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "タグ識別子です。"
},
"name": {
"type": "string",
"description": "タグの表示名です。"
},
"type": {
"type": "string",
"description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "このタグにバインドされたナレッジベースの数です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
}
}
}
}
}
}
},
"get": {
"tags": [
"タグ管理"
],
"summary": "ナレッジベースタグリストを取得",
"description": "ワークスペース内のすべてのナレッジベースタグのリストを返します。",
"operationId": "getKnowledgeTags",
"responses": {
"200": {
"description": "タグのリストです。",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "タグ識別子です。"
},
"name": {
"type": "string",
"description": "タグの表示名です。"
},
"type": {
"type": "string",
"description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "このタグにバインドされたナレッジベースの数です。"
}
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": [
{
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
]
}
}
}
}
}
}
},
"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 です。"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "新しいタグ名です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "タグが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "タグ識別子です。"
},
"name": {
"type": "string",
"description": "タグの表示名です。"
},
"type": {
"type": "string",
"description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "このタグにバインドされたナレッジベースの数です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
}
}
}
}
}
}
},
"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 です。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/tags/binding": {
"post": {
"tags": [
"タグ管理"
],
"summary": "タグをナレッジベースにバインド",
"description": "ナレッジベースに 1 つ以上のタグをバインドします。ナレッジベースには複数のタグを設定できます。",
"operationId": "bindTagsToDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tag_ids",
"target_id"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "バインドするタグ ID です。"
},
"target_id": {
"type": "string",
"description": "ナレッジベース ID です。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/tags/unbinding": {
"post": {
"tags": [
"タグ管理"
],
"summary": "タグとナレッジベースのバインドを解除",
"description": "ナレッジベースから 1 つまたは複数のタグを削除します。",
"operationId": "unbindTagFromDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"target_id"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "バインド解除するタグ ID のリストです。旧版の `tag_id` を指定しない限り必須です。"
},
"tag_id": {
"type": "string",
"deprecated": true,
"description": "旧版の単一タグ用フィールドです。サーバーサイドで `tag_ids` に正規化されます。新規連携では `tag_ids` を使用してください。"
},
"target_id": {
"type": "string",
"description": "ナレッジベース ID です。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/{dataset_id}/tags": {
"get": {
"tags": [
"タグ管理"
],
"summary": "ナレッジベースにバインドされたタグを取得",
"description": "特定のナレッジベースにバインドされたタグのリストを返します。",
"operationId": "queryDatasetTags",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"responses": {
"200": {
"description": "ナレッジベースにバインドされたタグです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "タグ識別子です。"
},
"name": {
"type": "string",
"description": "タグの表示名です。"
}
}
},
"description": "このナレッジベースにバインドされたタグのリスト。"
},
"total": {
"type": "integer",
"description": "このナレッジベースにバインドされたタグの合計数です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs"
}
],
"total": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata": {
"post": {
"tags": [
"メタデータ"
],
"summary": "メタデータフィールドを作成",
"description": "ナレッジベースのカスタムメタデータフィールドを作成します。メタデータフィールドを使用して、構造化された情報でドキュメントにアノテーションを付けることができます。",
"operationId": "createMetadataFieldJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"string",
"number",
"time"
],
"description": "`string` はテキスト値、`number` は数値、`time` は日付/時刻値です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
}
}
}
}
}
},
"responses": {
"201": {
"description": "メタデータフィールドが正常に作成されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの種類です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : メタデータ名が既に存在する、255 文字を超えている、または組み込みフィールドと競合しています。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Metadata name already exists."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"メタデータ"
],
"summary": "メタデータフィールドリストを取得",
"description": "ナレッジベースのすべてのメタデータフィールド（カスタムおよび組み込みの両方）の一覧と、各フィールドを使用しているドキュメント数を返します。",
"operationId": "listMetadataFieldsJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"responses": {
"200": {
"description": "ナレッジベースのメタデータフィールドです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_metadata": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの種類です。"
},
"count": {
"type": "integer",
"description": "このメタデータフィールドを使用しているドキュメント数です。"
}
}
},
"description": "メタデータフィールド定義のリスト。"
},
"built_in_field_enabled": {
"type": "boolean",
"description": "このナレッジベースで組み込みメタデータフィールドが有効かどうかです。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"doc_metadata": [
{
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string",
"count": 3
}
],
"built_in_field_enabled": true
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/{metadata_id}": {
"patch": {
"tags": [
"メタデータ"
],
"summary": "メタデータフィールドを更新",
"description": "カスタムメタデータフィールドの名前を変更します。",
"operationId": "updateMetadataFieldJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "metadata_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "メタデータフィールド ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "新しいメタデータフィールド名です。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "メタデータフィールドが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの種類です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : メタデータ名が既に存在する、255 文字を超えている、または組み込みフィールドと競合しています。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Metadata name already exists."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"メタデータ"
],
"summary": "メタデータフィールドを削除",
"description": "カスタムメタデータフィールドを完全に削除します。このフィールドを使用しているドキュメントは、該当するメタデータ値を失います。",
"operationId": "deleteMetadataFieldJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "metadata_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "メタデータフィールド ID です。"
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/built-in": {
"get": {
"tags": [
"メタデータ"
],
"summary": "組み込みメタデータフィールドを取得",
"description": "システムが提供する組み込みメタデータフィールドの一覧を返します（例：ドキュメントタイプ、ソース URL）。",
"operationId": "getBuiltInMetadataFieldsJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"responses": {
"200": {
"description": "組み込みメタデータフィールドです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"fields": {
"type": "array",
"description": "システム提供のメタデータフィールドのリストです。",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "組み込みフィールド識別子です。`document_name` はドキュメントタイトル、`uploader` は作成者、`upload_date` は作成日時、`last_update_date` は最終更新日時、`source` はドキュメントの出典を示します。"
},
"type": {
"type": "string",
"description": "フィールドのデータ型です。テキスト値の場合は `string`、日時値の場合は `time` です。"
}
}
}
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"fields": [
{
"name": "document_name",
"type": "string"
},
{
"name": "uploader",
"type": "string"
},
{
"name": "upload_date",
"type": "time"
},
{
"name": "last_update_date",
"type": "time"
},
{
"name": "source",
"type": "string"
}
]
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/built-in/{action}": {
"post": {
"tags": [
"メタデータ"
],
"summary": "組み込みメタデータフィールドを更新",
"description": "ナレッジベースの組み込みメタデータフィールドを有効または無効にします。",
"operationId": "toggleBuiltInMetadataFieldJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "action",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
},
"description": "`enable` で内蔵メタデータフィールドを有効化、`disable` で無効化します。"
}
],
"responses": {
"200": {
"description": "組み込みメタデータフィールドの切り替えに成功しました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作結果です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"result": "success"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/metadata": {
"post": {
"tags": [
"メタデータ"
],
"summary": "ドキュメントメタデータを一括更新",
"description": "複数のドキュメントのメタデータ値を一括更新します。リクエスト内の各ドキュメントに指定されたメタデータのキーと値のペアが適用されます。",
"operationId": "batchUpdateDocumentMetadataJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"operation_data"
],
"properties": {
"operation_data": {
"type": "array",
"items": {
"type": "object",
"required": [
"document_id",
"metadata_list"
],
"properties": {
"document_id": {
"type": "string",
"description": "メタデータを更新するドキュメントの ID です。"
},
"metadata_list": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールド ID です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"value": {
"description": "メタデータ値。文字列、数値、または `null` を指定できます。"
}
}
}
},
"partial_update": {
"type": "boolean",
"default": false,
"description": "メタデータを部分的に更新し、未指定フィールドの既存の値を保持するかどうかです。"
}
}
},
"description": "ドキュメントメタデータの更新操作の配列です。各エントリはドキュメント ID をメタデータのキーと値のペアにマッピングします。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ドキュメントメタデータが正常に更新されました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作結果です。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"result": "success"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 参照されたドキュメントが見つからない、またはこのナレッジベースで別のメタデータ操作が実行中です。",
"content": {
"application/json": {
"examples": {
"invalid_param_doc": {
"summary": "invalid_param (document)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document not found."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : このナレッジベースでは API アクセスが有効になっていません。\n- `forbidden` : サブスクリプションのナレッジベースリクエストのレート制限に達しました。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/workspaces/current/models/model-types/{model_type}": {
"get": {
"tags": [
"モデル"
],
"summary": "利用可能なモデルを取得",
"description": "タイプ別に利用可能なモデルの一覧を取得します。主にナレッジベース設定用の `text-embedding` モデルと `rerank` モデルのクエリに使用します。",
"operationId": "getAvailableModelsJa",
"parameters": [
{
"name": "model_type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"text-embedding",
"rerank",
"llm",
"tts",
"speech2text",
"moderation"
]
},
"description": "取得するモデルのタイプです。ナレッジベースの設定には、埋め込みモデルの場合は `text-embedding`、リランキングモデルの場合は `rerank` を使用します。"
}
],
"responses": {
"200": {
"description": "指定された種類で利用可能なモデルです。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "利用可能なモデルを持つモデルプロバイダーのリストです。",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "モデルプロバイダーの識別子です（例：`openai`、`cohere`）。"
},
"label": {
"type": "object",
"description": "プロバイダーのローカライズ表示名です。",
"properties": {
"en_US": {
"type": "string",
"description": "英語表示名。"
},
"zh_Hans": {
"type": "string",
"description": "中国語表示名。"
}
}
},
"icon_small": {
"type": "object",
"description": "プロバイダーの小アイコンの URL です。",
"properties": {
"en_US": {
"type": "string",
"description": "小アイコン URL。"
}
}
},
"icon_large": {
"type": "object",
"description": "プロバイダーの大アイコンの URL です。",
"properties": {
"en_US": {
"type": "string",
"description": "大アイコン URL。"
}
}
},
"status": {
"type": "string",
"description": "プロバイダーのステータスです。認証情報が設定済みで有効な場合は `active` です。"
},
"models": {
"type": "array",
"description": "このプロバイダーから利用可能なモデルのリストです。",
"items": {
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "モデル識別子です。ナレッジベースの作成または更新時に `embedding_model` の値として使用します。"
},
"label": {
"type": "object",
"description": "モデルのローカライズ表示名です。",
"properties": {
"en_US": {
"type": "string",
"description": "英語モデル名。"
},
"zh_Hans": {
"type": "string",
"description": "中国語モデル名。"
}
}
},
"model_type": {
"type": "string",
"description": "モデルのタイプです。`model_type` パスパラメータと一致します。"
},
"features": {
"type": "array",
"nullable": true,
"description": "モデルがサポートする機能です。なしの場合は `null` です。",
"items": {
"type": "string"
}
},
"fetch_from": {
"type": "string",
"description": "モデル定義の取得元です。`predefined-model` は組み込みモデル、`customizable-model` はユーザー設定モデルを示します。"
},
"model_properties": {
"type": "object",
"description": "`context_size` などのモデル固有のプロパティです。"
},
"status": {
"type": "string",
"description": "モデルの利用可能ステータスです。使用可能な場合は `active` です。"
}
}
}
}
}
}
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"data": [
{
"provider": "openai",
"label": {
"en_US": "OpenAI",
"zh_Hans": "OpenAI"
},
"icon_small": {
"en_US": "https://example.com/openai-small.svg"
},
"icon_large": {
"en_US": "https://example.com/openai-large.svg"
},
"status": "active",
"models": [
{
"model": "text-embedding-3-small",
"label": {
"en_US": "text-embedding-3-small",
"zh_Hans": "text-embedding-3-small"
},
"model_type": "text-embedding",
"features": null,
"fetch_from": "predefined-model",
"model_properties": {
"context_size": 8191
},
"status": "active"
}
]
}
]
}
}
}
}
}
}
}
}
},
"/datasets/pipeline/file-upload": {
"post": {
"tags": [
"ナレッジパイプライン"
],
"summary": "パイプラインファイルをアップロード",
"description": "ナレッジパイプラインで使用するファイルをアップロードします。`multipart/form-data` で単一ファイルを受け付けます。",
"operationId": "uploadPipelineFileJa",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "アップロードするファイルです。"
}
}
}
}
}
},
"responses": {
"201": {
"description": "ファイルが正常にアップロードされました。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "アップロードされたファイルの一意識別子です。"
},
"name": {
"type": "string",
"description": "元のファイル名です。"
},
"size": {
"type": "integer",
"description": "ファイルサイズ（バイト）。"
},
"extension": {
"type": "string",
"description": "ファイル拡張子。"
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "ファイルの MIME タイプです。アップロードに MIME タイプが含まれない場合、`null` となることがあります。"
},
"created_by": {
"type": "string",
"description": "ファイルをアップロードしたユーザーの ID。"
},
"created_at": {
"type": "string",
"nullable": true,
"description": "アップロードのタイムスタンプ（ISO 8601 形式）です。レコード作成中は `null` となることがあります。"
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "report.pdf",
"size": 524288,
"extension": "pdf",
"mime_type": "application/pdf",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": "2025-03-06T12:00:00"
}
}
}
}
}
},
"400": {
"description": "- `no_file_uploaded` : ファイルをアップロードしてください。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `too_many_files` : ファイルは 1 つのみ許可されています。",
"content": {
"application/json": {
"examples": {
"no_file_uploaded": {
"summary": "no_file_uploaded",
"value": {
"status": 400,
"code": "no_file_uploaded",
"message": "Please upload your file."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : ファイルサイズの上限を超えています。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 許可されていないファイルタイプです。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/datasource-plugins": {
"get": {
"tags": [
"ナレッジパイプライン"
],
"summary": "データソースプラグインリストを取得",
"description": "ナレッジパイプラインで設定されたデータソースノードを一覧表示します。各ノードには使用するプラグインと、ノードの実行に必要なメタデータが含まれます。",
"operationId": "listDatasourcePluginsJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "is_published",
"in": "query",
"schema": {
"type": "boolean",
"default": true
},
"description": "公開済みのパイプラインからノードを取得するかどうかです。デフォルトは `true` で、公開済みバージョンのノードを返します。"
}
],
"responses": {
"200": {
"description": "パイプラインに設定されているデータソースノードのリストです。",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "パイプラインワークフロー内のデータソースノードの ID です。 [データソースノードを実行](/api-reference/ナレッジパイプライン/データソースノードを実行) では `node_id` として、 [パイプラインを実行](/api-reference/ナレッジパイプライン/パイプラインを実行) では `start_node_id` として渡します。"
},
"plugin_id": {
"type": "string",
"description": "このノードを提供するデータソースプラグインの ID です。"
},
"provider_name": {
"type": "string",
"description": "データソースプラグインが登録するプロバイダー名です。"
},
"datasource_type": {
"type": "string",
"description": "データソースのタイプです。`local_file`、`online_document`、`online_drive`、`website_crawl` のいずれかです。"
},
"title": {
"type": "string",
"description": "ノードに設定されている表示タイトルです。"
},
"user_input_variables": {
"type": "array",
"description": "このデータソースに対して呼び出し元が指定するパイプライン入力変数です。ノードのデータソースパラメータ内の `{{#...#}}` 参照から導出されます。各要素はワークフローが使用するパイプライン変数のスキーマに従います。",
"items": {
"type": "object",
"additionalProperties": true
}
},
"credentials": {
"type": "array",
"description": "このデータソースの認証に利用できる資格情報のリストです。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資格情報の ID です。 [データソースノードを実行](/api-reference/ナレッジパイプライン/データソースノードを実行) では `credential_id` として、 [パイプラインを実行](/api-reference/ナレッジパイプライン/パイプラインを実行) の各データソース項目の `credential_id` フィールドとして渡します。"
},
"name": {
"type": "string",
"description": "資格情報の表示名です。"
},
"type": {
"type": "string",
"description": "データソースプラグインが定義する資格情報のタイプです。"
},
"is_default": {
"type": "boolean",
"description": "この資格情報がプロバイダーのデフォルトかどうかを示します。"
}
}
}
}
}
}
},
"examples": {
"success": {
"summary": "レスポンス例",
"value": [
{
"node_id": "1719288585006",
"plugin_id": "langgenius/notion_datasource",
"provider_name": "notion",
"datasource_type": "online_document",
"title": "Notion Documents",
"user_input_variables": [],
"credentials": [
{
"id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
"name": "Production Notion",
"type": "api-key",
"is_default": true
}
]
}
]
}
}
}
}
},
"400": {
"description": "`invalid_param` : このナレッジベースには処理パイプラインが設定されていません。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": {
"post": {
"tags": [
"ナレッジパイプライン"
],
"summary": "データソースノードを実行",
"description": "ナレッジパイプライン内の単一のデータソースノードを実行します。ノードの実行結果を含むストリーミングレスポンスを返します。",
"operationId": "runDatasourceNodeJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
},
{
"name": "node_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "実行するデータソースノードの ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"datasource_type",
"is_published"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "データソースノードの入力変数です。"
},
"datasource_type": {
"type": "string",
"enum": [
"online_document",
"local_file",
"website_crawl",
"online_drive"
],
"description": "データソースの種類です。"
},
"credential_id": {
"type": "string",
"nullable": true,
"description": "データソースとの認証に使用する認証情報の ID です。"
},
"is_published": {
"type": "boolean",
"description": "ノードの公開バージョンとドラフトバージョンのどちらを実行するかを指定します。`true` は公開バージョン、`false` はドラフトを実行します。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "ノード実行イベントを含むストリーミングレスポンスです。",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "ノード実行の進捗と結果を含む Server-Sent Events ストリームです。"
}
}
}
},
"400": {
"description": "`invalid_param` : このナレッジベースには処理パイプラインが設定されていない、またはリクエストボディの検証に失敗しました。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/run": {
"post": {
"tags": [
"ナレッジパイプライン"
],
"summary": "パイプラインを実行",
"description": "ナレッジベースの完全なナレッジパイプラインを実行します。ストリーミングとブロッキングの両方のレスポンスモードをサポートしています。",
"operationId": "runPipelineJa",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "ナレッジベース ID です。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"datasource_type",
"datasource_info_list",
"start_node_id",
"is_published",
"response_mode"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "パイプライン入力変数のキーと値のペア。ワークフローで定義されたパイプライン変数に対応します。入力変数がない場合は `{}` を渡してください。"
},
"datasource_type": {
"type": "string",
"enum": [
"local_file",
"online_document",
"website_crawl",
"online_drive"
],
"description": "データソースのタイプ。`datasource_info_list` の各項目に必要なフィールドを決定します。"
},
"datasource_info_list": {
"type": "array",
"description": "処理対象のデータソースオブジェクトのリストです。項目の構造は `datasource_type` によって異なります。",
"items": {
"oneOf": [
{
"title": "Local File",
"type": "object",
"required": [
"reference"
],
"properties": {
"reference": {
"type": "string",
"description": "[パイプラインファイルアップロード](/api-reference/ナレッジパイプライン/パイプラインファイルをアップロード) エンドポイントから返される `id` を使用してください。`related_id` もエイリアスとして使用可能です。"
},
"name": {
"type": "string",
"description": "ドキュメントのタイトルです。デフォルトは `\"untitled\"` です。"
}
}
},
{
"title": "Online Document",
"type": "object",
"required": [
"workspace_id",
"page"
],
"properties": {
"workspace_id": {
"type": "string",
"description": "外部プラットフォームのワークスペースまたはデータベース ID（例：Notion のワークスペース ID）。"
},
"page": {
"type": "object",
"description": "ページの詳細です。",
"required": [
"page_id",
"type"
],
"properties": {
"page_id": {
"type": "string",
"description": "ページ識別子です。"
},
"type": {
"type": "string",
"description": "データソースプラグインで定義されたページタイプ（例：`\"page\"`、`\"database\"`）。"
},
"page_name": {
"type": "string",
"description": "表示名です。デフォルトは `\"untitled\"` です。"
}
}
},
"credential_id": {
"type": "string",
"description": "外部プラットフォームとの認証用クレデンシャルです。Dify コンソールで管理します。省略した場合、プロバイダーのデフォルトクレデンシャルが使用されます。"
}
}
},
{
"title": "Website Crawl",
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "クロール対象の URL です。"
},
"title": {
"type": "string",
"description": "ドキュメント名として使用されます。デフォルトは `\"untitled\"` です。"
}
}
},
{
"title": "Online Drive",
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "ファイルまたはフォルダの ID です。"
},
"type": {
"type": "string",
"enum": [
"file",
"folder"
],
"description": "この項目が単一ファイルか、展開対象のフォルダかを指定します。"
},
"bucket": {
"type": "string",
"description": "ストレージバケット名です。一部のドライブプロバイダー（S3 互換ストレージなど）で必要です。プロバイダーがバケットを使用しない場合は省略できます。"
},
"name": {
"type": "string",
"description": "ファイル名です。デフォルトは `\"untitled\"` です。"
}
}
}
]
}
},
"start_node_id": {
"type": "string",
"description": "パイプライン実行を開始するノードの ID です。"
},
"is_published": {
"type": "boolean",
"description": "パイプラインの公開版またはドラフト版のどちらを実行するかを指定します。`true` は最新の公開版を実行し、`false` は現在のドラフトを実行します（未公開の変更をテストする場合に便利です）。"
},
"response_mode": {
"type": "string",
"enum": [
"streaming",
"blocking"
],
"description": "パイプライン実行のレスポンスモードです。`streaming` は Server-Sent Events ストリームを返し、`blocking` は完了まで待機して完全な結果を返します。"
}
}
},
"examples": {
"local_file": {
"summary": "リクエスト例—ローカルファイル",
"value": {
"inputs": {},
"datasource_type": "local_file",
"datasource_info_list": [
{
"reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "quarterly-report.pdf"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
},
"online_document": {
"summary": "リクエスト例—オンラインドキュメント",
"value": {
"inputs": {},
"datasource_type": "online_document",
"datasource_info_list": [
{
"workspace_id": "ws-abc123",
"page": {
"page_id": "pg-def456",
"type": "page",
"page_name": "Product Roadmap"
},
"credential_id": "cred-789xyz"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "streaming"
}
},
"website_crawl": {
"summary": "リクエスト例—ウェブサイトクロール",
"value": {
"inputs": {},
"datasource_type": "website_crawl",
"datasource_info_list": [
{
"url": "https://example.com/docs/getting-started",
"title": "Getting Started Guide"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
},
"online_drive": {
"summary": "リクエスト例—オンラインドライブ",
"value": {
"inputs": {},
"datasource_type": "online_drive",
"datasource_info_list": [
{
"id": "file-abc123",
"type": "file",
"bucket": "my-bucket",
"name": "meeting-notes.docx"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
}
}
}
}
},
"responses": {
"200": {
"description": "パイプライン実行結果。フォーマットは `response_mode` に依存します：ストリーミングは `text/event-stream` を返し、ブロッキングは完全な JSON 結果を返します。",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events ストリームです。各行は `data: {JSON}\\n\\n` 形式です。主要なイベント：`workflow_started`（実行開始）、`node_started` / `node_finished`（ノードごとの進捗、`node_id`、`node_type`、`status`、`inputs`、`outputs` を含む）、`workflow_finished`（最終結果、`status`、`outputs`、`total_tokens`、`elapsed_time` を含む）、`ping`（キープアライブ）。"
}
},
"application/json": {
"schema": {
"type": "object",
"description": "パイプライン実行の完全な結果です。`response_mode` が `blocking` の場合に返されます。",
"additionalProperties": true
},
"examples": {
"success": {
"summary": "Blocking Response Example",
"value": {
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
"data": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
"status": "succeeded",
"outputs": {},
"created_at": 1741267200,
"finished_at": 1741267210
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : このナレッジベースには処理パイプラインが設定されていない、またはリクエストボディの検証に失敗しました。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : このナレッジベースでは API アクセスが有効になっていません。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : ナレッジベースが見つかりません。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
},
"500": {
"description": "`pipeline_run_error` : パイプライン実行に失敗しました。",
"content": {
"application/json": {
"examples": {
"pipeline_run_error": {
"summary": "pipeline_run_error",
"value": {
"status": 500,
"code": "pipeline_run_error",
"message": "Pipeline execution failed: connection timeout"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Dataset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ナレッジベースの一意識別子です。"
},
"name": {
"type": "string",
"description": "ナレッジベースの表示名です。ワークスペース内で一意です。"
},
"description": {
"type": "string",
"description": "ナレッジベースの目的または内容を説明するオプションのテキストです。"
},
"provider": {
"type": "string",
"description": "プロバイダータイプです。内部管理の場合は `vendor`、外部ナレッジベース接続の場合は `external` です。"
},
"permission": {
"type": "string",
"description": "このナレッジベースにアクセスできるユーザーを制御します。指定可能な値：`only_me`、`all_team_members`、`partial_members`。"
},
"data_source_type": {
"type": "string",
"description": "ドキュメントのデータソースタイプです。まだ設定されていない場合は `null` です。"
},
"indexing_technique": {
"type": "string",
"description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。"
},
"app_count": {
"type": "integer",
"description": "現在このナレッジベースを使用しているアプリケーションの数です。"
},
"document_count": {
"type": "integer",
"description": "ナレッジベース内のドキュメント総数です。"
},
"word_count": {
"type": "integer",
"description": "全ドキュメントの合計単語数です。"
},
"created_by": {
"type": "string",
"description": "ナレッジベースを作成したユーザーの ID です。"
},
"author_name": {
"type": "string",
"description": "作成者の表示名です。"
},
"created_at": {
"type": "number",
"description": "作成タイムスタンプ（Unix エポック、秒単位）です。"
},
"updated_by": {
"type": "string",
"description": "ナレッジベースを最後に更新したユーザーの ID です。"
},
"updated_at": {
"type": "number",
"description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。"
},
"embedding_model": {
"type": "string",
"description": "インデックス作成に使用される埋め込みモデルの名前です。"
},
"embedding_model_provider": {
"type": "string",
"description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。"
},
"embedding_available": {
"type": "boolean",
"description": "設定された埋め込みモデルが現在利用可能かどうかです。"
},
"retrieval_model_dict": {
"type": "object",
"description": "ナレッジベースの検索設定です。",
"properties": {
"search_method": {
"type": "string",
"description": "検索に使用する検索方法です。`keyword_search` はキーワードマッチング、`semantic_search` は埋め込みベースの類似度検索、`full_text_search` は全文インデックス検索、`hybrid_search` はセマンティックとキーワードの組み合わせ検索を示します。"
},
"reranking_enable": {
"type": "boolean",
"description": "リランキングが有効かどうかです。"
},
"reranking_mode": {
"type": "string",
"nullable": true,
"description": "リランキングモードです。`reranking_model` はモデルベースのリランキング、`weighted_score` はスコアベースの重み付けを示します。リランキングが無効の場合は `null` です。"
},
"reranking_model": {
"type": "object",
"description": "リランキングモデルの設定です。",
"properties": {
"reranking_provider_name": {
"type": "string",
"description": "リランキングモデルのプロバイダー名です。"
},
"reranking_model_name": {
"type": "string",
"description": "リランキングモデル名です。"
}
}
},
"weights": {
"type": "object",
"nullable": true,
"description": "ハイブリッド検索の重み設定です。",
"properties": {
"weight_type": {
"type": "string",
"description": "セマンティック検索とキーワード検索の重みを調整するための戦略です。"
},
"vector_setting": {
"type": "object",
"description": "セマンティック検索の重み設定です。",
"properties": {
"vector_weight": {
"type": "number",
"description": "セマンティック（ベクトル）検索結果に割り当てられた重みです。"
},
"embedding_provider_name": {
"type": "string",
"description": "ベクトル検索に使用される埋め込みモデルのプロバイダーです。"
},
"embedding_model_name": {
"type": "string",
"description": "ベクトル検索に使用される埋め込みモデルの名前です。"
}
}
},
"keyword_setting": {
"type": "object",
"description": "キーワード検索の重み設定です。",
"properties": {
"keyword_weight": {
"type": "number",
"description": "キーワード検索結果に割り当てられた重みです。"
}
}
}
}
},
"top_k": {
"type": "integer",
"description": "返す結果の最大数です。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "スコア閾値フィルタリングが有効かどうかです。"
},
"score_threshold": {
"type": "number",
"description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の場合にのみ有効です。"
}
}
},
"summary_index_setting": {
"type": "object",
"nullable": true,
"description": "サマリーインデックスの設定です。",
"properties": {
"enable": {
"type": "boolean",
"description": "サマリーインデックスが有効かどうかです。"
},
"model_name": {
"type": "string",
"description": "要約生成に使用されるモデルの名前です。"
},
"model_provider_name": {
"type": "string",
"description": "要約生成モデルのプロバイダーです。"
},
"summary_prompt": {
"type": "string",
"description": "要約生成に使用されるプロンプトテンプレートです。"
}
}
},
"tags": {
"type": "array",
"description": "このナレッジベースに関連付けられたタグです。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "タグ識別子です。"
},
"name": {
"type": "string",
"description": "Tag name."
},
"type": {
"type": "string",
"description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。"
}
}
}
},
"doc_form": {
"type": "string",
"description": "ドキュメントのチャンキングモードです。`text_model` は標準テキストチャンキング、`hierarchical_model` は親子構造、`qa_model` は QA ペア抽出を示します。"
},
"external_knowledge_info": {
"type": "object",
"nullable": true,
"description": "外部ナレッジベースの接続詳細です。`provider` が `external` の場合に存在します。",
"properties": {
"external_knowledge_id": {
"type": "string",
"description": "外部ナレッジベースの ID です。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部ナレッジ API 接続の ID です。"
},
"external_knowledge_api_name": {
"type": "string",
"description": "外部ナレッジ API の表示名です。"
},
"external_knowledge_api_endpoint": {
"type": "string",
"description": "外部ナレッジ API のエンドポイント URL です。"
}
}
},
"external_retrieval_model": {
"type": "object",
"nullable": true,
"description": "外部ナレッジベースの検索設定です。内部ナレッジベースの場合は `null` です。",
"properties": {
"top_k": {
"type": "integer",
"description": "外部ナレッジベースから返す結果の最大数です。"
},
"score_threshold": {
"type": "number",
"description": "最小関連性スコアのしきい値です。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "スコア閾値フィルタリングが有効かどうかです。"
}
}
},
"doc_metadata": {
"type": "array",
"description": "ナレッジベースのメタデータフィールド定義です。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの値の種類です。"
}
}
}
},
"built_in_field_enabled": {
"type": "boolean",
"description": "組み込みメタデータフィールド（例：`document_name`、`uploader`）が有効かどうかです。"
},
"pipeline_id": {
"type": "string",
"nullable": true,
"description": "カスタム処理パイプラインが設定されている場合のパイプライン ID です。"
},
"runtime_mode": {
"type": "string",
"nullable": true,
"description": "ランタイム処理モードです。"
},
"chunk_structure": {
"type": "string",
"nullable": true,
"description": "チャンク構造の設定です。"
},
"icon_info": {
"type": "object",
"nullable": true,
"description": "ナレッジベースのアイコン表示設定です。",
"properties": {
"icon_type": {
"type": "string",
"description": "アイコンの種類です。"
},
"icon": {
"type": "string",
"description": "アイコン識別子または絵文字です。"
},
"icon_background": {
"type": "string",
"description": "アイコンの背景色です。"
},
"icon_url": {
"type": "string",
"description": "カスタムアイコン画像の URL です。"
}
}
},
"is_published": {
"type": "boolean",
"description": "ナレッジベースが公開済みかどうかです。"
},
"total_documents": {
"type": "integer",
"description": "ドキュメントの合計数です。"
},
"total_available_documents": {
"type": "integer",
"description": "有効で利用可能なドキュメントの数です。"
},
"enable_api": {
"type": "boolean",
"description": "このナレッジベースで API アクセスが有効かどうかです。"
},
"is_multimodal": {
"type": "boolean",
"description": "マルチモーダルコンテンツ処理が有効かどうかです。"
},
"maintainer": {
"type": "string",
"nullable": true,
"description": "ナレッジベースのメンテナーの表示名です。設定されていない場合は `null` です。"
},
"partial_member_list": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "`permission` が `partial_members` の場合にアクセスを許可されたメンバーのアカウント ID です。更新レスポンスでは常に含まれ、詳細レスポンスでは `permission` が `partial_members` の場合にのみ含まれます。"
}
}
},
"Document": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ドキュメントの一意識別子です。"
},
"position": {
"type": "integer",
"description": "リスト内のドキュメントの表示位置です。"
},
"data_source_type": {
"type": "string",
"description": "ドキュメントの作成方法です。ファイルアップロードの場合は `upload_file`、Notion インポートの場合は `notion_import` です。"
},
"data_source_info": {
"type": "object",
"description": "生のデータソース情報です。`data_source_type` によって異なります。"
},
"data_source_detail_dict": {
"type": "object",
"description": "ファイル詳細を含む詳細なデータソース情報です。"
},
"dataset_process_rule_id": {
"type": "string",
"description": "このドキュメントに適用された処理ルールの ID です。"
},
"name": {
"type": "string",
"description": "ドキュメント名です。"
},
"created_from": {
"type": "string",
"description": "ドキュメントの作成元です。API で作成した場合は `api`、UI で作成した場合は `web` です。"
},
"created_by": {
"type": "string",
"description": "ドキュメントを作成したユーザーの ID です。"
},
"created_at": {
"type": "number",
"description": "作成タイムスタンプ（Unix エポック、秒単位）です。"
},
"tokens": {
"type": "integer",
"description": "ドキュメント内の合計トークン数です。"
},
"indexing_status": {
"type": "string",
"description": "現在のインデックスステータスです。`waiting` はキュー待ち、`parsing` はコンテンツ抽出中、`cleaning` はノイズ除去中、`splitting` はチャンキング中、`indexing` はベクトル構築中、`completed` は準備完了、`error` は失敗、`paused` は手動一時停止を示します。"
},
"error": {
"type": "string",
"nullable": true,
"description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。"
},
"enabled": {
"type": "boolean",
"description": "このドキュメントが検索に対して有効かどうかです。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "ドキュメントが無効化されたタイムスタンプです。有効な場合は `null` です。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "ドキュメントを無効化したユーザーの ID です。有効な場合は `null` です。"
},
"archived": {
"type": "boolean",
"description": "ドキュメントがアーカイブ済みかどうかです。"
},
"display_status": {
"type": "string",
"description": "`indexing_status` と `enabled` 状態から導出されたユーザー向け表示ステータスです。"
},
"word_count": {
"type": "integer",
"description": "ドキュメントの合計単語数です。"
},
"hit_count": {
"type": "integer",
"description": "ドキュメントが検索クエリでマッチした回数です。"
},
"doc_form": {
"type": "string",
"description": "ドキュメントのチャンキングモードです。`text_model` は標準テキストチャンキング、`hierarchical_model` は親子構造、`qa_model` は QA ペア抽出を示します。"
},
"doc_metadata": {
"type": "array",
"description": "このドキュメントに割り当てられたメタデータ値です。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "メタデータフィールドの識別子です。"
},
"name": {
"type": "string",
"description": "メタデータフィールド名です。"
},
"type": {
"type": "string",
"description": "メタデータフィールドの値の種類です。"
},
"value": {
"type": "string",
"description": "このドキュメントのメタデータ値。"
}
}
}
},
"summary_index_status": {
"type": "string",
"nullable": true,
"description": "このドキュメントの要約インデックスのステータスです。要約インデックスが設定されていない場合は `null` です。"
},
"need_summary": {
"type": "boolean",
"description": "このドキュメントに要約を生成する必要があるかどうかです。"
}
}
},
"Segment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "チャンクの一意識別子です。"
},
"position": {
"type": "integer",
"description": "ドキュメント内のチャンクの位置。"
},
"document_id": {
"type": "string",
"description": "このチャンクが属するドキュメントの ID です。"
},
"content": {
"type": "string",
"description": "チャンクのテキスト内容です。"
},
"sign_content": {
"type": "string",
"description": "整合性検証用の署名付きコンテンツハッシュです。"
},
"answer": {
"type": "string",
"description": "回答コンテンツです。Q&A モードのドキュメントで使用されます。"
},
"word_count": {
"type": "integer",
"description": "チャンク内容の単語数です。"
},
"tokens": {
"type": "integer",
"description": "チャンク内容のトークン数です。"
},
"keywords": {
"type": "array",
"description": "キーワードベースの検索のためにこのチャンクに関連付けられたキーワードです。",
"items": {
"type": "string"
}
},
"index_node_id": {
"type": "string",
"description": "ベクトルストア内のインデックスノードの ID です。"
},
"index_node_hash": {
"type": "string",
"description": "インデックスされたコンテンツのハッシュです。変更の検出に使用されます。"
},
"hit_count": {
"type": "integer",
"description": "このチャンクが検索クエリでマッチした回数です。"
},
"enabled": {
"type": "boolean",
"description": "このチャンクが検索に対して有効かどうかです。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "チャンクが無効化されたタイムスタンプです。有効な場合は `null` です。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "チャンクを無効化したユーザーの ID です。有効な場合は `null` です。"
},
"status": {
"type": "string",
"description": "チャンクの現在のインデックスステータスです（例：`completed`、`indexing`、`error`）。"
},
"created_by": {
"type": "string",
"description": "チャンクを作成したユーザーの ID です。"
},
"created_at": {
"type": "number",
"description": "作成タイムスタンプ（Unix エポック、秒単位）です。"
},
"updated_at": {
"type": "number",
"description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。"
},
"updated_by": {
"type": "string",
"description": "このチャンクを最後に更新したユーザーの ID です。"
},
"indexing_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が開始されたタイムスタンプです。まだ開始されていない場合は `null` です。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が完了したタイムスタンプです。まだ完了していない場合は `null` です。"
},
"error": {
"type": "string",
"nullable": true,
"description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "インデックス作成が停止されたタイムスタンプです。停止されていない場合は `null` です。"
},
"child_chunks": {
"type": "array",
"description": "このチャンクに属する子チャンクです。階層モードのドキュメントにのみ存在します。",
"items": {
"$ref": "#/components/schemas/ChildChunk"
}
},
"attachments": {
"type": "array",
"description": "このチャンクに添付されたファイルです。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "添付ファイルの識別子です。"
},
"name": {
"type": "string",
"description": "元のファイル名です。"
},
"size": {
"type": "integer",
"description": "ファイルサイズ（バイト）。"
},
"extension": {
"type": "string",
"description": "ファイル拡張子。"
},
"mime_type": {
"type": "string",
"description": "ファイルの MIME タイプ。"
},
"source_url": {
"type": "string",
"description": "添付ファイルにアクセスする URL です。"
}
}
}
},
"summary": {
"type": "string",
"nullable": true,
"description": "AI が生成したチャンクコンテンツの要約です。要約インデックスが有効でない場合は `null` です。"
}
}
},
"ChildChunk": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "子チャンクの一意識別子です。"
},
"segment_id": {
"type": "string",
"description": "この子チャンクが属する親チャンクの ID です。"
},
"content": {
"type": "string",
"description": "子チャンクのテキスト内容です。"
},
"position": {
"type": "integer",
"description": "親チャンク内の子チャンクの位置です。"
},
"word_count": {
"type": "integer",
"description": "子チャンク内容の単語数です。"
},
"type": {
"type": "string",
"description": "子チャンクの作成方法です。API から作成または更新された子チャンクは常に `customized` です。システム生成の子チャンクは `automatic` です。"
},
"created_at": {
"type": "number",
"description": "作成タイムスタンプ（Unix エポック、秒単位）です。"
},
"updated_at": {
"type": "number",
"description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。"
}
}
},
"RetrievalModel": {
"type": "object",
"required": [
"search_method",
"reranking_enable",
"top_k",
"score_threshold_enabled"
],
"properties": {
"search_method": {
"type": "string",
"description": "検索に使用される検索メソッドです。",
"enum": [
"keyword_search",
"semantic_search",
"full_text_search",
"hybrid_search"
]
},
"reranking_enable": {
"type": "boolean",
"description": "リランキングが有効かどうかです。"
},
"reranking_model": {
"type": "object",
"description": "リランキングモデルの設定です。",
"properties": {
"reranking_provider_name": {
"type": "string",
"description": "リランキングモデルのプロバイダー名です。"
},
"reranking_model_name": {
"type": "string",
"description": "リランキングモデル名です。"
}
}
},
"reranking_mode": {
"type": "string",
"enum": [
"reranking_model",
"weighted_score"
],
"nullable": true,
"description": "リランキングモードです。`reranking_enable` が `true` の場合は必須です。"
},
"top_k": {
"type": "integer",
"description": "返す結果の最大数です。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "スコア閾値フィルタリングが有効かどうかです。"
},
"score_threshold": {
"type": "number",
"nullable": true,
"description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の場合にのみ有効です。"
},
"weights": {
"type": "object",
"nullable": true,
"description": "ハイブリッド検索の重み設定です。",
"properties": {
"weight_type": {
"type": "string",
"description": "セマンティック検索とキーワード検索の重みを調整するための戦略です。",
"enum": [
"semantic_first",
"keyword_first",
"customized"
]
},
"vector_setting": {
"type": "object",
"description": "セマンティック検索の重み設定です。",
"properties": {
"vector_weight": {
"type": "number",
"description": "セマンティック（ベクトル）検索結果に割り当てられた重みです。"
},
"embedding_provider_name": {
"type": "string",
"description": "ベクトル検索に使用される埋め込みモデルのプロバイダーです。"
},
"embedding_model_name": {
"type": "string",
"description": "ベクトル検索に使用される埋め込みモデルの名前です。"
}
}
},
"keyword_setting": {
"type": "object",
"description": "キーワード検索の重み設定です。",
"properties": {
"keyword_weight": {
"type": "number",
"description": "キーワード検索結果に割り当てられた重みです。"
}
}
}
}
},
"metadata_filtering_conditions": {
"type": "object",
"nullable": true,
"description": "ドキュメントのメタデータが指定した条件に一致するチャンクのみを取得対象に絞り込みます。条件はサーバーサイドで評価されます。",
"properties": {
"logical_operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"nullable": true,
"description": "複数の条件を組み合わせる方法です。"
},
"conditions": {
"type": "array",
"nullable": true,
"description": "評価するメタデータ条件のリストです。",
"items": {
"type": "object",
"required": [
"name",
"comparison_operator"
],
"properties": {
"name": {
"type": "string",
"description": "比較対象とするメタデータフィールド名です。"
},
"comparison_operator": {
"type": "string",
"description": "適用する比較方法です。文字列演算子（`contains`、`not contains`、`start with`、`end with`、`is`、`is not`、`empty`、`not empty`、`in`、`not in`）は文字列または配列のメタデータに作用します。数値演算子（`=`、`≠`、`>`、`<`、`≥`、`≤`）は数値メタデータに作用します。時刻演算子（`before`、`after`）は時刻メタデータに作用します。",
"enum": [
"contains",
"not contains",
"start with",
"end with",
"is",
"is not",
"empty",
"not empty",
"in",
"not in",
"=",
"≠",
">",
"<",
"≥",
"≤",
"before",
"after"
]
},
"value": {
"nullable": true,
"description": "比較対象の値です。型は `comparison_operator` によって異なります。ほとんどの文字列演算子では文字列、`in` および `not in` では文字列配列、数値演算子では数値、`empty` および `not empty` では省略します。",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "number"
}
]
}
}
}
}
}
}
}
}
},
"securitySchemes": {
"ApiKeyAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API_KEY",
"description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**API Key が欠落または無効な場合、HTTP `401` とエラーコード `unauthorized` が返されます。"
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink