クエリトークンを作成

クエリを実行 用のクエリトークンを発行し、そのトークンとともに送信するリクエストボディを返します。詳細は ナレッジベースへのクエリ を参照してください。

POST /knowledge-fs/spaces/{knowledge_base_id}/queries/admission

cURL

request

curl --request POST \ --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/queries/admission \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "mode": "fast", "query": "What changed in the refund policy this quarter?" } '

200

success

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

Authorizations

Authorization · string · header · required

すべてのリクエストは、Authorization: Bearer {API_KEY} ヘッダーに指定した API キーで認証します。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。

キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーがない、または無効な場合は HTTP 401（unauthorized）が返ります。

Path Parameters

knowledge_base_id · string<uuid> · required

ナレッジベース ID です。ナレッジベースの API アクセス ダイアログに表示されるサービス API エンドポイントの最後のセグメント（…/knowledge-fs/spaces/<knowledge base ID>）です。アドレスバーでは /datasets/new/ の後のセグメントです。

Body

application/json

不明なフィールドが含まれていると 400 が返ります。

nullable と記されたオプションフィールドでは、null は省略と同じ扱いになります。

空白のみではない query を指定してください。

query · string · required

質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。

Maximum string length: 16000

Pattern: \S

activeDocumentIds · string[]

これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。空のままにしてください。

Maximum array length: 100

activeEntityIds · string[]

これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。空のままにしてください。

Maximum array length: 100

mode · enum<string> | null

検索の深度です。fast、deep、research のいずれかを指定します（検索の深度 を参照）。省略する（または null を送信する）と、ナレッジベースのデフォルトの深度が使われます。これは ナレッジベース設定を取得 の retrieval.default_mode です。

Available options: fast, deep, research, null

sessionId · string | null

クエリセッションの ID（UUID）です。省略すると新しいセッションが開始されます。クエリを実行 は、レスポンスヘッダー x-session-id でセッション ID を返します。

セッションには直近 20 件のクエリが保存されますが、それらが後の回答に反映されることはありません。クエリがないまま 30 分が経過すると、期限切れになります。

期限切れまたは不明な ID を指定すると、その ID で新しいセッションが開始されます。そのため、自分で生成した UUID も、そのセッションの ID としてそのまま有効です。

Response

200

application/json

クエリトークンが発行されました。

expires_at · string

トークンの有効期限です（UTC の ISO 8601 タイムスタンプ）。発行から最大 60 秒後です。デプロイ環境によっては、有効期間がさらに短く設定されている場合があります。

operation_id · string

常に createQuery で、トークンが有効な操作を示します。呼び出し元はこの値を無視して構いません。

request · object

クエリを実行 のリクエストボディです。変更せずに送信してください。

Show child attributes

token · string

このナレッジベースに対する クエリを実行 用のクエリトークンで、expires_at まで有効です。Authorization: Bearer <token> として送信してください。

再試行も含め、呼び出しごとに新しいトークンを作成してください。

署名付きの JWT です。X-Trace-ID ヘッダーには、このレスポンスの trace_id を使用してください。トークンをデコードする必要はありません。

trace_id · string

クエリを実行 の X-Trace-ID ヘッダーとして送信する値です。トークンの trace_id クレームと同じ値で、クエリ記録 ID ではありません。

url · string

クエリを実行 の送信先です。デプロイ環境で SERVICE_API_URL が設定されている場合は絶対 URL です。それ以外の場合はパス /v1/knowledge-fs/query-stream で、すでに /v1 プレフィックスを含みます。このパスは、エンドポイントのパスではなく、エンドポイントのスキームとホストを基準に解決してください。