> ## 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.

# Quickstart

> Install the Krun Python SDK, set your API key and make your first decision.

This guide takes you from an API key to your first decision. You need Python 3.10 or later and a Krun API key.

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    pip install krun-ai
    ```

    The package is [`krun-ai` on PyPI](https://pypi.org/project/krun-ai/). You import it as `krun`.
  </Step>

  <Step title="Set your API key">
    The SDK reads the key from the `KRUN_API_KEY` environment variable.

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      export KRUN_API_KEY=krun_live_...
      ```

      ```powershell Windows PowerShell theme={null}
      $env:KRUN_API_KEY = "krun_live_..."
      ```
    </CodeGroup>

    <Warning>
      Keep your API key on the server. Never ship it in browser or mobile client code. See [Authentication](/api-reference/authentication).
    </Warning>
  </Step>

  <Step title="Make a decision">
    Create `decide.py`:

    ```python decide.py theme={null}
    from krun import Krun

    client = Krun()  # reads KRUN_API_KEY

    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",
                },
            }
        },
    )

    answer = result.answers["department"]
    print(answer.choice)         # returns
    print(answer.confidence)     # 0.967536
    print(answer.probabilities)  # {'shipping': 0.011351, 'returns': 0.978886, 'billing': 0.009763}
    print(result.request_id)     # req_...
    ```

    Run it:

    ```bash theme={null}
    python decide.py
    ```
  </Step>

  <Step title="Handle abstention">
    When the model is not confident enough, it abstains: `answer.choice` is `None` and `answer.abstain` is `True`. The probabilities are still there if you want a best guess.

    ```python theme={null}
    if answer.choice is None:
        best_guess = max(answer.probabilities, key=answer.probabilities.get)
        send_to_human(best_guess)
    else:
        route(answer.choice)
    ```

    See [Abstention](/concepts/abstention) for when to trust this signal.
  </Step>
</Steps>

<Note>
  The numbers above come from a real call. Your values can differ slightly between calls and model updates, so don't hard-code them in tests.
</Note>

## Use the HTTP API directly

The same request with curl:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.krun.ai/v1/decide \
    -H "Authorization: Bearer $KRUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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"
          }
        }
      }
    }'
  ```

  ```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",
              },
          }
      },
  )
  print(result.answers["department"].choice)
  ```

  ```text TypeScript (coming soon) theme={null}
  The TypeScript SDK (@krun-ai/sdk) is not published on npm yet.
  Use the HTTP API from Node.js until it is released.
  See /sdks/typescript for its status.
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "model": "krun-one-v0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 0.967536,
      "probabilities": {
        "shipping": 0.011351,
        "returns": 0.978886,
        "billing": 0.009763
      },
      "abstain": false,
      "abstention_status": "advisory"
    }
  },
  "usage": {
    "input_tokens": 49
  }
}
```

The request id is in the `X-Request-ID` response header (`curl -i` shows it). You need it to [send feedback](/guides/feedback).

<Tip>
  The first request after a period without traffic can take longer while the model starts. The SDK's default 70-second timeout covers this. See [Production best practices](/guides/production-best-practices#timeouts-and-cold-starts).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Questions and answers" icon="list-check" href="/concepts/questions-and-answers">
    How requests and answers are structured.
  </Card>

  <Card title="Multiple questions" icon="layer-group" href="/guides/multiple-questions">
    Ask several questions about the same text in one call.
  </Card>

  <Card title="Tool routing" icon="screwdriver-wrench" href="/guides/tool-routing">
    Pick a tool for an agent step.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    Async client, errors, timeouts and retries.
  </Card>
</CardGroup>