Skip to main content
The official SDKs call the same REST API. They track decision identifiers and state versions during a conversation. Your application only needs to persist the session ID if it wants to resume after a restart.

Quickstart — Python and TypeScript

Install the SDK and run your first exchange in your preferred language.

Updates and versions

Installed SDKs do not update automatically. Run these commands from your project, then restart or redeploy your application.
In a uv project that already uses zelinqa, update the lockfile and environment, then print the installed version:
Updates respect the constraint in pyproject.toml. If it pins an exact version, change it explicitly. For example, to select 1.0.1:
If you use pip instead of uv, run this in your application’s virtual environment:
With pip, also update your dependency file or lockfile using your usual tooling: this command does not rewrite them.

Check before deploying

  1. Read the changelog and SDK changes.
  2. Test a complete conversation against a demo domain: start, free-text or choice answers as applicable, progress, and stopping. Also test session recovery and the errors your application handles.
  3. Commit the manifest and lockfile (pyproject.toml + uv.lock, or package.json + package-lock.json) to deploy the dependencies you tested. Avoid uncontrolled updates to the latest release in production.
The version commands above do not call the Zelinqa API; a test conversation uses your key and quotas. Updating the SDK does not republish your domain or change the configuration version attached to an existing session. MCP has its own environment and update procedure.

Keys and permissions

Create a key in Zelinqa Studio. Configuration keys can be created as soon as the domain exists, before any publication; a key with the Conversations (runtime) permission requires a published version. Each key belongs to its domain and has permissions: A runtime key cannot read configuration. You may create several keys for one domain, each with the permissions its service needs. Use a separate key for each domain.
These are server-side clients. Never put an API key in a browser, mobile application, public repository, or model conversation.
In Python, ZelinqaClient() reads ZELINQA_API_KEY. For configuration, ZelinqaConfigurationClient() checks ZELINQA_CONFIGURATION_API_KEY first, then ZELINQA_API_KEY. In TypeScript, pass apiKey explicitly to the constructor. The default URL is https://api.zelinqa.ai; an HTTP URL can be used locally, but not with a real key over an untrusted network.

Conversation lifecycle

  1. start_session / startSession creates a session on the currently active published version.
  2. session.next() returns the first decision, with no previous answer.
  3. Your application displays candidates[0].text and collects the person’s actual answer.
  4. session.answer(...) attaches it to the pending decision and returns the next decision. Do not call next() again just to get that question.
  5. session.refresh() reads the state; session.submit_feedback(...) records a business result that was actually observed.
For an open question, send the person’s words (user_text / userText). For closed or semi-open questions, choice_labels / choiceLabels takes the exact displayed labels and resolves choice IDs locally. A semi-open answer may add free_text / freeText. For a genuine unanswered question or refusal, use asked_no_answer or refused without text. Choices alone and these two outcomes need no model analysis; free text may require it. The handle tracks state_version. Use it sequentially: concurrent mutations to the same session may conflict. After an interruption or ZelinqaStateVersionConflictError, read the state and reconcile the answer before retrying; do not replay blindly. An existing session remains pinned to its published version after a later publication.

Other operations

Publication is asynchronous: check the terminal compilation status before treating the new version as active. HTTP failures have typed errors for authentication, permissions, validation, conflicts, and rate limits. The SDKs retry transient failures with a stable idempotency key per logical call; business conflicts are not hidden. For options, response models, and configuration examples, see the Python guide, TypeScript guide, or API reference.