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

# Quickstart

> Get a question, submit an answer, and track your dimensions with Python or TypeScript.

**Run a complete first exchange with the SDK**, from your backend. For a host such as Claude Desktop or Cursor, use [Connect the MCP server](/en/quickstart/mcp) instead.

## 1. Prepare your domain

You need a [published domain](/en/quickstart/configure-domain) and an [API key with the runtime permission](/en/quickstart/generate-api-key). If you already have both, skip to installation.

<Warning>Keep the key on your server. Never put it in a browser, mobile application, public repository, or prompt.</Warning>

## 2. Install and run

Choose your language. The program displays the first question, waits for your answer, then displays the next decision and dimension statuses. For this terminal demo, enter text for an open question or **one exact label** for a choice.

<Tabs>
  <Tab title="Python">
    Python 3.11 or later. With [uv](https://docs.astral.sh/uv/guides/projects/), work in your project directory; if it is not initialized yet, run `uv init --python 3.11`. If you prefer pip, use an activated virtual environment.

    <CodeGroup>
      ```bash uv theme={null}
      uv add zelinqa
      ```

      ```bash pip theme={null}
      python -m pip install zelinqa
      ```
    </CodeGroup>

    Then set the key in your terminal:

    ```bash theme={null}
    export ZELINQA_API_KEY="YOUR_RUNTIME_KEY"
    ```

    Save the code as `demo.py`, then run **`uv run python demo.py`** (or `python demo.py` with pip, in the activated environment). The Python client reads the environment variable automatically.

    ```python theme={null}
    from zelinqa import ZelinqaClient

    with ZelinqaClient() as client:
        session = client.start_session(client_reference="demo-001")
        decision = session.next()

        if decision.action == "ask":
            question = decision.candidates[0]
            print(question.text)
            for choice in question.choices:
                print(f"- {choice.label}")

            reply = input("> ")
            if not reply.strip():
                decision = session.answer(outcome="asked_no_answer")
            elif question.choices:
                decision = session.answer(choice_labels=[reply])
            else:
                decision = session.answer(reply)

            print(decision.action, decision.warnings)
            for dimension in decision.progress.dimensions:
                print(dimension.id, dimension.effective_status)
            if decision.action == "ask":
                print(decision.candidates[0].text)
    ```
  </Tab>

  <Tab title="TypeScript">
    Node.js 22 or later. Install the package and set the key in your terminal:

    ```bash theme={null}
    npm install @zelinqa/sdk
    export ZELINQA_API_KEY="YOUR_RUNTIME_KEY"
    ```

    This example is also executable JavaScript: save it as `demo.mjs`, then run `node demo.mjs`. The TypeScript client receives the key explicitly in its constructor.

    ```ts theme={null}
    import { createInterface } from "node:readline/promises";
    import { stdin, stdout } from "node:process";
    import { ZelinqaClient } from "@zelinqa/sdk";

    const client = new ZelinqaClient({ apiKey: process.env.ZELINQA_API_KEY ?? "" });
    const session = await client.startSession({ client_reference: "demo-001" });
    let decision = await session.next();
    const question = decision.candidates[0];

    if (decision.action === "ask" && question !== undefined) {
      console.log(question.text);
      for (const choice of question.choices) {
        console.log(`- ${choice.label}`);
      }

      const input = createInterface({ input: stdin, output: stdout });
      try {
        const reply = await input.question("> ");
        if (!reply.trim()) {
          decision = await session.answer({ outcome: "asked_no_answer" });
        } else if (question.choices.length > 0) {
          decision = await session.answer({ choiceLabels: [reply] });
        } else {
          decision = await session.answer({ userText: reply });
        }
        console.log(decision.action, decision.warnings);
        for (const dimension of decision.progress.dimensions) {
          console.log(dimension.id, dimension.effective_status);
        }
        if (decision.action === "ask") {
          console.log(decision.candidates[0]?.text);
        }
      } finally {
        input.close();
      }
    }
    ```
  </Tab>
</Tabs>

## 3. Understand the result

* The first question comes from **your published domain**: its wording depends on your configuration.
* `answer(...)` records the answer **and already returns the next decision**. Do not call `next()` again to get that same continuation.
* `progress.dimensions` contains each dimension's status, such as `in_progress` or `covered`.
* `warnings` can report a reached turn limit or successful qualification. Your application decides whether to continue.
* `action: "stop"` means no question is available. Do not access the first candidate in that case.

The SDK tracks question IDs, decision IDs, and the state version. **Your business logic does not need to construct them.** Persist `session.id` in your backend to resume after a restart.

## Next steps

<CardGroup cols={2}>
  <Card title="A complete conversation" icon="comments" href="/en/guides/complete-conversation">Run a terminal chatbot and hand confirmed information to your application.</Card>
  <Card title="Answers and context" icon="message" href="/en/guides/answers-context">Multiple choices, semi-open answers, refusals, and already-known data.</Card>
  <Card title="Progress and qualification" icon="chart-line" href="/en/concepts/qualification">Understand dimensions and Essential, Balanced, and Deep qualification.</Card>
  <Card title="SDK reference" icon="code" href="/en/integrations/sdk">Clients, permissions, methods, and advanced configuration.</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.