Create Query Token
Issues a query token for Run Query and returns the request body to send with it. See Query the Knowledge Base for details.
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?"
}
'{
"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
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path Parameters
Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.
Body
Unknown fields answer 400.
Optional fields marked nullable treat null as omitted.
Provide a nonblank query.
The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.
16000\SThese IDs do not filter or rank retrieved content. Leave empty.
100These IDs do not filter or rank retrieved content. Leave empty.
100Retrieval depth: fast, deep, or research (see Retrieval Depth). Omit it (or send null) to use the knowledge base's default depth, retrieval.default_mode in Get Knowledge Base Settings.
fast, deep, research, null ID of a query session, as a UUID. Omit it to start a new session. Run Query returns the session ID in its x-session-id response header.
A session stores the last 20 queries but doesn't carry them into later answers. It expires after 30 minutes without a query.
An expired or unknown ID starts a fresh session under that ID, so a UUID you generate yourself stays valid as that session's ID.
Response
Query token issued.
When the token expires, as an ISO 8601 timestamp in UTC. At most 60 seconds after issue. The deployment can shorten the lifetime.
Always createQuery, the operation the token is valid for. Callers can ignore it.
Was this page helpful?
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?"
}
'{
"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"
}