> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # クエリトークンを作成 > [クエリを実行](/ja/api-reference/queries/run-query) 用のクエリトークンを発行し、そのトークンとともに送信するリクエストボディを返します。詳細は [ナレッジベースへのクエリ](/ja/api-reference/guides/knowledge-base#query-the-knowledge-base) を参照してください。 ## OpenAPI ````yaml /ja/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/queries/admission openapi: 3.0.1 info: description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 title: Dify サービス API version: 1.0.0 servers: - description: Dify サービス API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - description: チャットメッセージとインタラクションに関連する操作です。 name: チャットメッセージ - description: ファイルのアップロードとプレビューの操作です。 name: ファイル操作 - description: エンドユーザー情報に関連する操作です。 name: エンドユーザー - description: ユーザーフィードバックの操作です。 name: メッセージフィードバック - description: 会話管理に関連する操作です。 name: 会話管理 - description: テキスト読み上げと音声認識の操作です。 name: 音声・テキスト変換 - description: アプリケーション設定と情報を取得する操作です。 name: アプリケーション設定 - description: ダイレクト返信用のアノテーション管理に関連する操作です。 name: アノテーション管理 - description: 人間の入力を要する一時停止中のワークフローの再開操作です。 name: 人間の入力 - description: ワークフローの実行と管理のための操作です。 name: ワークフロー実行 - description: テキスト生成に関連する操作です。 name: 完了メッセージ - description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 name: ナレッジベース - description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 name: ドキュメント - description: ドキュメントチャンクと子チャンクの管理のための操作です。 name: チャンク - description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 name: メタデータ - description: ナレッジベースタグとタグバインディングの管理のための操作です。 name: タグ管理 - description: 利用可能なモデルを取得するための操作です。 name: モデル - description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 name: ナレッジパイプライン - description: ナレッジベースに質問し、回答をストリーミングで受け取ります。 name: クエリ - description: クエリが何を検索したか、またその理由を確認します。 name: クエリ記録 - description: リサーチの質問をバックグラウンドで実行し、その結果を取得します。 name: リサーチタスク - description: ナレッジベースのドキュメントと、そのファイル、リビジョン、チャンクを読み取り、ドキュメントにメタデータのラベルを付けます。 name: ドキュメントとチャンク - description: インデックス処理の追跡、キャンセル、再試行と、ナレッジベースのバックグラウンドタスクの一覧表示を行います。 name: インデックスタスク - description: ドキュメントファイル、ファイルのバッチ、またはソースの削除を、完了するまで追跡します。 name: 削除ジョブ - description: ナレッジベースにデータを供給するソース、その同期スケジュール、接続を管理します。 name: ソース - description: ソースの即時同期、ウェブサイトのページまたはプロバイダーのアイテムのインポート、実行の追跡、キャンセル、再試行を行います。 name: ソースの同期とインポート - description: ナレッジベースのモデルと検索設定の読み取りと変更、および変更によって始まる移行の追跡を行います。 name: 設定 paths: /knowledge-fs/spaces/{knowledge_base_id}/queries/admission: post: tags: - Queries summary: クエリトークンを作成 description: >- [クエリを実行](/ja/api-reference/queries/run-query) 用のクエリトークンを発行し、そのトークンとともに送信するリクエストボディを返します。詳細は [ナレッジベースへのクエリ](/ja/api-reference/guides/knowledge-base#query-the-knowledge-base) を参照してください。 operationId: createQueryToken parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: リクエスト例 - 新しいセッション value: mode: fast query: What changed in the refund policy this quarter? request_session: summary: リクエスト例 - セッション ID あり value: activeDocumentIds: [] activeEntityIds: [] mode: fast query: What is the refund window for monthly plans? sessionId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d schema: additionalProperties: false description: 空白のみではない `query` を指定してください。 properties: activeDocumentIds: description: これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。空のままにしてください。 items: type: string maxItems: 100 type: array activeEntityIds: description: これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。空のままにしてください。 items: type: string maxItems: 100 type: array mode: description: >- 検索の深度です。`fast`、`deep`、`research` のいずれかを指定します（[検索の深度](/ja/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth) を参照）。省略する（または `null` を送信する）と、ナレッジベースのデフォルトの深度が使われます。これは [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) の `retrieval.default_mode` です。 enum: - fast - deep - research - null nullable: true type: string query: description: 質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。 maxLength: 16000 nullable: false pattern: \S type: string sessionId: description: >- クエリセッションの ID（UUID）です。省略すると新しいセッションが開始されます。[クエリを実行](/ja/api-reference/queries/run-query) は、レスポンスヘッダー `x-session-id` でセッション ID を返します。 セッションには直近 20 件のクエリが保存されますが、それらが後の回答に反映されることはありません。クエリがないまま 30 分が経過すると、期限切れになります。 期限切れまたは不明な ID を指定すると、その ID で新しいセッションが開始されます。そのため、自分で生成した UUID も、そのセッションの ID としてそのまま有効です。 nullable: true type: string required: - query type: object description: |- 不明なフィールドが含まれていると `400` が返ります。 nullable と記されたオプションフィールドでは、`null` は省略と同じ扱いになります。 required: true responses: '200': content: application/json: examples: success: summary: レスポンス例 - 新しいセッション value: expires_at: '2026-09-06T08:31:07Z' operation_id: createQuery request: activeDocumentIds: [] activeEntityIds: [] knowledgeSpaceId: 8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f mode: fast query: What changed in the refund policy this quarter? token: >- eyJhbGciOiJSUzI1NiIsImtpZCI6Imtmcy0yMDI2LTA5In0.eyJpc3MiOiJkaWZ5LWNvbnRyb2wtcGxhbmUiLCJhdWQiOiJrbm93bGVkZ2UtZnMiLCJzdWIiOiJkaWZ5LWRhdGFzZXQtYXBpLWtleTo3YjRjOWUyMS0zZDVmLTRhNmItOGM3ZC05ZTBmMWEyYjNjNGQiLCJhY3Rpb24iOiJxdWVyaWVzLmNyZWF0ZSIsInRyYWNlX2lkIjoiM2YxZTlhN2MtMmI0ZC00ZTZmLThhOTAtMWIyYzNkNGU1ZjYwIiwiZXhwIjoxNzg4NjgzNDY3fQ.V2s9Rm5xR2ZUZ0J2M2Q5aW1KU3hqUXJsV1pKcGtnQUFCZUtGMQ trace_id: 3f1e9a7c-2b4d-4e6f-8a90-1b2c3d4e5f60 url: https://api.example.com/v1/knowledge-fs/query-stream success_session: summary: レスポンス例 - セッション ID あり value: expires_at: '2026-09-06T08:33:52Z' operation_id: createQuery request: activeDocumentIds: [] activeEntityIds: [] knowledgeSpaceId: 8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f mode: fast query: What is the refund window for monthly plans? sessionId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d token: >- eyJhbGciOiJSUzI1NiIsImtpZCI6Imtmcy0yMDI2LTA5In0.eyJpc3MiOiJkaWZ5LWNvbnRyb2wtcGxhbmUiLCJhdWQiOiJrbm93bGVkZ2UtZnMiLCJzdWIiOiJkaWZ5LWRhdGFzZXQtYXBpLWtleTo3YjRjOWUyMS0zZDVmLTRhNmItOGM3ZC05ZTBmMWEyYjNjNGQiLCJhY3Rpb24iOiJxdWVyaWVzLmNyZWF0ZSIsInRyYWNlX2lkIjoiN2Q0YTFjOGUtNWY2MC00YjIzLTlhN2QtOGUwZjFhMmIzYzRkIiwiZXhwIjoxNzg4NjgzNjMyfQ.TnBHc0xxUjBkWWJ4M2VBaW1KU3hqUXJsV1pKcGtnQUFCZUtGMg trace_id: 7d4a1c8e-5f60-4b23-9a7d-8e0f1a2b3c4d url: https://api.example.com/v1/knowledge-fs/query-stream schema: properties: expires_at: description: >- トークンの有効期限です（UTC の ISO 8601 タイムスタンプ）。発行から最大 60 秒後です。デプロイ環境によっては、有効期間がさらに短く設定されている場合があります。 type: string operation_id: description: 常に `createQuery` で、トークンが有効な操作を示します。呼び出し元はこの値を無視して構いません。 type: string request: description: >- [クエリを実行](/ja/api-reference/queries/run-query) のリクエストボディです。変更せずに送信してください。 properties: activeDocumentIds: description: 送信されたドキュメント ID です。省略した場合は `[]` です。 items: type: string type: array activeEntityIds: description: 送信されたエンティティ ID です。省略した場合は `[]` です。 items: type: string type: array knowledgeSpaceId: description: >- ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。この値はトークンに結び付けられており、[クエリを実行](/ja/api-reference/queries/run-query) は `knowledgeSpaceId` がトークンと一致しないボディを拒否します。 type: string mode: description: 送信された検索の深度です。省略した場合は `null` です。 nullable: true type: string query: description: リクエストで送信した質問です。リクエストに画像の参照が含まれる場合は `null` になることがあります。 maxLength: 16000 nullable: true pattern: \S type: string sessionId: description: 送信されたセッション ID です。省略した場合は含まれません。 nullable: true type: string type: object token: description: >- このナレッジベースに対する [クエリを実行](/ja/api-reference/queries/run-query) 用のクエリトークンで、`expires_at` まで有効です。`Authorization: Bearer ` として送信してください。 再試行も含め、呼び出しごとに新しいトークンを作成してください。 署名付きの JWT です。`X-Trace-ID` ヘッダーには、このレスポンスの `trace_id` を使用してください。トークンをデコードする必要はありません。 type: string trace_id: description: >- [クエリを実行](/ja/api-reference/queries/run-query) の `X-Trace-ID` ヘッダーとして送信する値です。トークンの `trace_id` クレームと同じ値で、クエリ記録 ID ではありません。 type: string url: description: >- [クエリを実行](/ja/api-reference/queries/run-query) の送信先です。デプロイ環境で `SERVICE_API_URL` が設定されている場合は絶対 URL です。それ以外の場合はパス `/v1/knowledge-fs/query-stream` で、すでに `/v1` プレフィックスを含みます。このパスは、エンドポイントのパスではなく、エンドポイントのスキームとホストを基準に解決してください。 type: string type: object description: クエリトークンが発行されました。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - query type: string_too_long description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized_1: summary: unauthorized (header missing) value: code: unauthorized message: >- Authorization header must be provided and start with 'Bearer' status: 401 unauthorized_2: summary: unauthorized (key unknown) value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：`Authorization` ヘッダーがないか、キーが不明であるか、ナレッジベースの API キーではありません。 - `knowledge_fs_invalid_credential`：キーは有効ですが、キーのワークスペースにこの ID のナレッジベースが存在しないか、キーがワークスペースに紐付いていません。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `knowledge_fs_access_denied`：トークンの発行中に、このナレッジベースに対するキーのアクセス権が取り消されました。 - `forbidden`：Dify Cloud で、ワークスペースがサブスクリプションで定められたナレッジベースのリクエストレート制限に達しました。読み取りを含め、すべての呼び出しがカウントされます。 '404': content: application/json: examples: not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: '- `not_found`：このデプロイ環境では Agent ナレッジベース機能が無効になっています。' '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 description: >- - `knowledge_fs_operation_unavailable`：このワークスペースで Agent ナレッジベース機能が設定されていないか、このデプロイ環境ではこの操作を利用できません。または、リクエストの認可中に、このナレッジベースに対するキーのアクセス権が変更されました。新しいトークンを取得してください。 - `knowledge_fs_operation_unavailable`：このナレッジベースは従来型ナレッジベースからアップグレードされたものです。従来型ナレッジベースで無効化またはアーカイブされていたドキュメントを、まだ無効化している途中です。後で再試行してください。 components: securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.