# Query an engine (/docs/api/query)
<EndpointLayout>
<EndpointHeader method="POST" path="/v1/engine/query" />

Searches the engine's linked sources, writes an answer from them, and checks every citation before it returns. `lynk.query` calls it for you.

<EndpointExamples>
<CodeTabs>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/engine/query \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "engine_id": "your-engine-id",
        "query": "What is the refund window?",
        "top_k": 8,
        "query_mode": "grounded"
      }'
    ```
  </Tab>
  <Tab value="Python">
    ```python
    from docklee import Lynk

    lynk = Lynk(engine_id="your-engine-id")
    result = lynk.query_sync("What is the refund window?", mode="grounded")
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import { Lynk, type KnowledgeResult } from 'docklee';

    const lynk = new Lynk({ engineId: 'your-engine-id' });
    const result = (await lynk.query('What is the refund window?', { mode: 'grounded' })) as KnowledgeResult;
    ```
  </Tab>
</CodeTabs>

<Tabs items={['200', '402']}>
  <Tab value="200">
    ```json
    {
      "answer": "Customers can request a refund within 30 days of purchase.",
      "citations": [
        {
          "chunk_id": "c2a8f5e1-7b39-4d6c-a014-8e3f2b9d61c7",
          "page_number": 4,
          "section_title": "Refunds and returns"
        }
      ],
      "confidence": 0.93
    }
    ```
  </Tab>
  <Tab value="402">
    ```json
    {
      "detail": "Monthly token limit exceeded."
    }
    ```
  </Tab>
</Tabs>
</EndpointExamples>

## Body [#body]

<ApiFields>
  <ApiField name="engine_id" type="string<uuid>" required>
    The engine to ask.
  </ApiField>
  <ApiField name="query" type="string" required>
    The question, in plain words.
  </ApiField>
  <ApiField name="top_k" type="integer" defaultValue="8">
    How many chunks to search for, from 1 to 50. Your plan can cap it lower.
  </ApiField>
  <ApiField name="query_mode" type="string" defaultValue="precise">
    `grounded`, `blended`, or `retrieval`. `precise` and `guide` mean `grounded`, and `explore` means `blended`. See [Answer modes](/docs/knowledge/answers/answer-modes).
  </ApiField>
  <ApiField name="model_id" type="string | null">
    A generation model your plan includes, up to 128 characters. Leave it out to use the engine's model.
  </ApiField>
</ApiFields>

## Response [#response]

<ApiFields>
  <ApiField name="answer" type="string" required>
    The answer, written from your sources.
  </ApiField>
  <ApiField name="citations" type="object[]" required>
    The chunks the answer is based on. Each has `chunk_id`, `page_number`, and `section_title`.
  </ApiField>
  <ApiField name="confidence" type="number" required>
    How well the sources support the answer, from 0 to 1. `0` when no citation was valid. See [Citations and confidence](/docs/knowledge/answers/citations-and-confidence).
  </ApiField>
</ApiFields>

## Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | The engine answered. |
| `400` | The question couldn't be answered as sent. The `detail` says why. |
| `401` | The key is missing, malformed, or revoked. |
| `402` | Your plan's monthly allowance is used up. |
| `403` | The key's capability or scope doesn't allow reading this engine. |
| `404` | The engine doesn't exist in the key's workspace. |
| `422` | A field is missing or invalid. |
| `429` | A rate limit was hit. |
</EndpointLayout>
