> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecisional.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Knowledge Engine

> Streams a response to a natural language query using Server-Sent Events

Query a knowledge engine with a natural language question. This endpoint uses Server-Sent Events (SSE) to stream the response back to the client.

### Request Format

<ParamField body="query" type="string" required>
  The natural language query to ask the knowledge engine
</ParamField>

<ParamField body="name" type="string" required>
  A name for this query workflow
</ParamField>

<ParamField body="context_id" type="string">
  Context ID used in case of thread mode for chat based workflows
</ParamField>

<ParamField body="advanced_reasoning" type="boolean">
  Flag to enable advanced reasoning for the query
</ParamField>

<ParamField body="model" type="string">
  The model to use for the query
</ParamField>

### Example Request

```json theme={null}
{
  "query": "What were the company's revenue figures for 2023?",
  "name": "Revenue Analysis",
  "advanced_reasoning": true,
  "model": "llama-v3-70b"
}
```

### Response Format

The response is streamed using Server-Sent Events (SSE) with the following event types:

* `message`: Contains intermediate response chunks as they are generated
* `error`: Contains error messages if something goes wrong
* `done`: Final event containing the complete response with metadata

### Example Response Stream

```javascript theme={null}
// Intermediate messages
event: message
data: "Based on the available information, "
event: message
data: "the company's revenue in 2023 was "
event: message
data: "$1.2 billion, representing a 15% increase from 2022."
// Final response with complete result
event: done
data: {
"id": "wf_abc123xyz789",
"name": "Revenue Analysis",
"query": "What were the company's revenue figures for 2023?",
"type": "query",
"knowledge_engine_id": "kng_abc123xyz789",
"status": "processed",
"response": "Based on the available information, the company's revenue in 2023 was $1.2 billion, representing a 15% increase from 2022.",
"citations": [
{
"text": "In fiscal year 2023, total revenue reached $1.2B, up 15% YoY",
"source": "Annual Report 2023",
"page": 45
}
],
"created_at": 1679644800
}
```

### Notes

* The streaming response allows for real-time display of the AI's response as it's being generated
* The final `done` event includes the complete response along with metadata and citations
* If an error occurs, the stream will emit an `error` event and close the connection
* Clients should handle connection closure appropriately using the `close` event

<Note>
  The streaming response requires a client that supports Server-Sent Events (SSE). Most modern browsers and HTTP clients support this feature.
</Note>

### Response Object

<ResponseField name="id" type="string">
  Unique identifier for the workflow
</ResponseField>

<ResponseField name="name" type="string">
  Name of the workflow
</ResponseField>

<ResponseField name="query" type="string">
  The original query that was asked
</ResponseField>

<ResponseField name="type" type="string">
  Type of workflow (always "query")
</ResponseField>

<ResponseField name="knowledge_engine_id" type="string">
  ID of the knowledge engine that was queried
</ResponseField>

<ResponseField name="status" type="string">
  Status of the workflow ("processed" when complete)
</ResponseField>

<ResponseField name="response" type="string">
  The complete response text
</ResponseField>

<ResponseField name="citations" type="array">
  Array of citations supporting the response

  <Expandable title="Citation Object">
    <ResponseField name="text" type="string">
      The relevant text from the source
    </ResponseField>

    <ResponseField name="source" type="string">
      Name of the source document
    </ResponseField>

    <ResponseField name="page" type="number">
      Page number in the source document
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="number">
  Unix timestamp when the workflow was created
</ResponseField>


## OpenAPI

````yaml POST /api/v1/knowledge-engines/{id}/query
openapi: 3.0.1
info:
  title: Knowledge Engine API
  description: Public API endpoints for managing knowledge engines
  version: 1.0.0
servers:
  - url: https://api.getdecisional.ai
security: []
paths:
  /api/v1/knowledge-engines/{id}/query:
    post:
      summary: Query Knowledge Engine
      description: Streams a response to a natural language query using Server-Sent Events
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Knowledge engine ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
                - name
              properties:
                query:
                  type: string
                  description: The natural language query
                name:
                  type: string
                  description: Name of the workflow
                advanced_reasoning:
                  type: boolean
                  description: Enable advanced reasoning
                model:
                  type: string
                  description: LLM to use for the query
                  enum:
                    - auto
                    - claude-4.5-sonnet
                    - llama-v3-70b
                    - llama-4-scout
                    - llama-4-maverick
                    - gemini-2.5
                    - gpt-5.4
                    - claude-4.6-haiku
                    - gpt-4.1
                  example: llama-v3-70b
                context_id:
                  type: string
                  description: Context ID for maintaining conversation history in chat mode
      responses:
        '200':
          description: Streaming response using Server-Sent Events
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Bad Request - Various validation and state errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_knowledge_engine_id:
                  summary: Invalid Knowledge Engine ID
                  value:
                    error: Invalid knowledge engine ID
                knowledge_engine_not_ready:
                  summary: Knowledge Engine Not Ready
                  value:
                    error: 'knowledge engine is not ready, current status: processing'
                no_active_data_sources:
                  summary: No Active Data Sources
                  value:
                    error: knowledge engine has no active data sources
                invalid_model:
                  summary: Invalid Model
                  value:
                    error: Model unsupported-model not supported
                model_not_enabled:
                  summary: Model Not Enabled
                  value:
                    error: Model Claude 3.5 Sonnet is not enabled
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: >-
            Invalid knowledge engine name: exceeds maximum length of 50
            characters

````