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
Body
Unknown fields answer 400.
Optional fields marked nullable treat null as omitted.
Provide a nonblank query.
Retrieval 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.
Request body for Run Query. Send it unchanged.
Show child attributes
Show child attributes
Query token for Run Query on this knowledge base, good until expires_at. Send it as Authorization: Bearer <token>.
Create a new token for each call, including a retry.
It is a signed JWT. Read trace_id from this response for the X-Trace-ID header; you do not need to decode the token.
Value to send as the X-Trace-ID header of Run Query. It equals the token's trace_id claim. It is not the query record ID.
Where to send Run Query. An absolute URL when the deployment sets SERVICE_API_URL. Otherwise the path /v1/knowledge-fs/query-stream, which already carries the /v1 prefix. Resolve that form against the scheme and host of your endpoint, not against the endpoint's path.
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"
}