REST API

The REST API lets your backend integrate directly with Zelinqa. The SDKs and MCP server use the same API. Your backend keeps the identifiers returned by Zelinqa and calls the engine whenever your experience needs a new question.

Responsibilities

Your application	Zelinqa
Display or rephrase the question	Select the best candidates
Keep `session_id` and `state_version`	Maintain canonical session state
Send the answer that was actually observed	Understand the answer and update progress
Decide when to end the experience	Report warnings; stop at the turn limit or when no question remains
Protect the API key on the server	Enforce isolation, scopes, and idempotency

Recommended loop

Create a session once with POST /v1/sessions.
Call /next with the latest state_version.
Use candidates[0], or select another candidate if your product requires it.
After the answer, call /next again with previous_turn.
Send external information through /events. Its response carries the pending decision recomputed on the updated state: when it has changed, ask its question instead of the earlier one.
Submit the final outcome through /feedback.

If your backend restarts, read the session with GET /v1/sessions/{session_id}. Do not rebuild state from a stale local copy.

Choice answers

When your interface displays choices provided by Zelinqa, return their choice_id values in structured_answer.choice_ids. This avoids unnecessary semantic interpretation and preserves deterministic mapping.

Prefer structured answers

When your application already knows what an answer means, send that interpretation directly:

previous_turn.outcome reports whether the question was answered, left unanswered, or explicitly refused;
structured_answer.choice_ids sends selections from a closed or semi-open question;
client_updates.data sends business data already validated by your system.

{
  "state_version": 3,
  "previous_turn": {
    "decision_id": "dec_7f2a",
    "question_id": "q_budget",
    "outcome": "asked_answered",
    "user_text": "My maximum budget is 3,000 euros."
  },
  "client_updates": {
    "data": [
      { "id": "info_budget", "operation": "set", "value": 3000 }
    ]
  }
}

The confirmed client_updates value is applied as structured data. Here the question is open: even with a confirmed data value, the person’s actual answer in user_text is required and may be analyzed by the engine. For a closed or semi-open question, choice_ids alone suffice when the person adds no text; that path may avoid model analysis. Never invent an uncertain value.

outcome describes the result of the question, but does not replace user_text for an answered open question or create business data by itself. Also send structured_answer or client_updates when your system knows the information obtained.

HTTP calls with curl

Follow the complete curl example.

API reference

Explore routes, schemas, and response codes.

Call Zelinqa from your backend. Never expose a key in browser JavaScript or a mobile bundle.

API guides

Sessions

Configuration

Service

Responsibilities

Recommended loop

Choice answers

Prefer structured answers

HTTP calls with curl

API reference