Quickstart

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

1. Prepare your domain

You need a published domain and an API key with the runtime permission. If you already have both, skip to installation.

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

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.

Python
TypeScript

Python 3.11 or later. With uv, 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.

uv add zelinqa

python -m pip install zelinqa

Then set the key in your terminal:

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.

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)

Node.js 22 or later. Install the package and set the key in your terminal:

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.

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();
  }
}

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

A complete conversation

Run a terminal chatbot and hand confirmed information to your application.

Answers and context

Multiple choices, semi-open answers, refusals, and already-known data.

Progress and qualification

Understand dimensions and Essential, Balanced, and Deep qualification.

SDK reference

Clients, permissions, methods, and advanced configuration.

Get started

Guides

References

Resources

1. Prepare your domain

2. Install and run

3. Understand the result

Next steps

A complete conversation

Answers and context

Progress and qualification

SDK reference

​1. Prepare your domain

​2. Install and run

​3. Understand the result

​Next steps

A complete conversation

Answers and context

Progress and qualification

SDK reference

1. Prepare your domain

2. Install and run

3. Understand the result

Next steps