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

> ## Agent Instructions
> Krun API base URL: https://api.krun.ai. Authenticate server-side with `Authorization: Bearer $KRUN_API_KEY`; never put a Krun API key in browser code.
> Prefer the Python SDK in examples: `pip install krun-ai`, `from krun import Krun`. The TypeScript SDK `@krun-ai/sdk` is not published on npm yet: do not tell users to `npm install` it.
> The only question type is `choice`. `confidence` is the top-1 minus top-2 probability margin, not the probability that the answer is correct. `choice` is null when `abstain` is true.
> Usage reports `input_tokens` only. There are no output tokens.

# Feedback

> Tell Krun whether an answer was correct with POST /v1/feedback, using the request id from the X-Request-ID header.

Send feedback when you learn whether an answer was right, for example when an agent corrects a routed ticket. Feedback is recorded per answer and helps track errors on real traffic.

```http theme={null}
POST /v1/feedback
```

```json theme={null}
{
  "request_id": "req_0cf5441281f640ffbf0111c5a3ed9e50",
  "question_id": "department",
  "correct": false,
  "expected_decision": "billing"
}
```

| Field               | Required | Description                                                                     |
| ------------------- | -------- | ------------------------------------------------------------------------------- |
| `request_id`        | Yes      | The `X-Request-ID` of the `/v1/decide` call.                                    |
| `question_id`       | Yes      | The question the feedback is about. Required also for single-question requests. |
| `correct`           | Yes      | Whether the answer was right.                                                   |
| `expected_decision` | No       | The option id that should have been chosen. Up to 200 characters.               |
| `metadata`          | No       | A JSON object, up to 8 KiB serialized. Don't put personal data here.            |

## Get the request id

Every `/v1/decide` response carries its request id in the `X-Request-ID` header. It is not in the JSON body.

<Tabs>
  <Tab title="Python SDK">
    The SDK reads the header for you:

    ```python theme={null}
    result = client.decide(context=..., questions=...)
    print(result.request_id)  # req_0cf5441281f640ffbf0111c5a3ed9e50
    ```
  </Tab>

  <Tab title="curl">
    Use `-i` to print the response headers:

    ```bash theme={null}
    curl -i https://api.krun.ai/v1/decide \
      -H "Authorization: Bearer $KRUN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "context": "...", "questions": { ... } }'
    ```

    ```http theme={null}
    HTTP/2 200
    content-type: application/json
    x-request-id: req_0cf5441281f640ffbf0111c5a3ed9e50
    ```
  </Tab>

  <Tab title="TypeScript (coming soon)">
    The TypeScript SDK will expose the id as `result.requestId`. It is not published on npm yet. See [TypeScript SDK](/sdks/typescript).
  </Tab>
</Tabs>

You can also set your own id by sending an `X-Request-ID` header with the decision: 1 to 128 characters of letters, digits, `.`, `_`, `:` and `-`. Krun keeps it and returns it. Otherwise Krun generates one like `req_...`. With the Python SDK, pass `request_id=` to `decide()`.

Store the request id with the decision in your system, so you can send feedback later.

## Send feedback

<CodeGroup>
  ```python Python theme={null}
  from krun import Krun

  client = Krun()

  result = client.decide(
      context="Customer wants to return an item.",
      questions={
          "department": {
              "type": "choice",
              "options": {
                  "shipping": "Shipping and delivery issues",
                  "returns": "Returns and refunds",
                  "billing": "Billing and payment issues",
              },
          }
      },
  )

  # Later, once you know the right department:
  client.feedback(
      request_id=result.request_id,
      question_id="department",
      correct=False,
      expected_decision="billing",
      metadata={"ticket": "T-1234"},
  )
  ```

  ```bash curl theme={null}
  curl https://api.krun.ai/v1/feedback \
    -H "Authorization: Bearer $KRUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "request_id": "req_0cf5441281f640ffbf0111c5a3ed9e50",
      "question_id": "department",
      "correct": false,
      "expected_decision": "billing"
    }'
  ```
</CodeGroup>

The API returns `201 Created`:

```json theme={null}
{
  "id": "fb_...",
  "object": "feedback",
  "request_id": "req_0cf5441281f640ffbf0111c5a3ed9e50",
  "question_id": "department",
  "created_at": "2026-09-24T13:05:12Z"
}
```

## Rules

* The `request_id` must belong to a decision made by the same project. Any API key of the project can send feedback. Otherwise the API returns `404 NOT_FOUND`.
* Krun does not store the content of your requests, so it can't check that the request had a question with that `question_id`. Send the id you used in the request.
* Send one feedback call per answer. For a request with three questions, send up to three calls.
* Feedback is never retried automatically by the SDK, because the API has no idempotency key. If a call fails with a network error, check before sending it again.