Get the next questions

curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/next \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 1,
  "previous_turn": {
    "decision_id": "<string>",
    "question_id": "<string>",
    "assistant_text": "<string>",
    "user_text": "<string>",
    "message_id": "<string>"
  },
  "context_update": {
    "mode": "summary",
    "text": "<string>"
  },
  "client_updates": {
    "data": [
      {
        "id": "<string>",
        "value": "<string>",
        "operation": "set"
      }
    ],
    "dimensions": [
      {
        "id": "<string>",
        "operation": "set"
      }
    ],
    "objective": {
      "operation": "set"
    }
  },
  "selection": {
    "candidate_count": 5,
    "allowed_question_types": [],
    "required_target_ids": [
      "<string>"
    ],
    "excluded_question_ids": [
      "<string>"
    ]
  }
}
'

import requests

url = "https://api.zelinqa.ai/v1/sessions/{session_id}/next"

payload = {
    "state_version": 1,
    "previous_turn": {
        "decision_id": "<string>",
        "question_id": "<string>",
        "assistant_text": "<string>",
        "user_text": "<string>",
        "message_id": "<string>"
    },
    "context_update": {
        "mode": "summary",
        "text": "<string>"
    },
    "client_updates": {
        "data": [
            {
                "id": "<string>",
                "value": "<string>",
                "operation": "set"
            }
        ],
        "dimensions": [
            {
                "id": "<string>",
                "operation": "set"
            }
        ],
        "objective": { "operation": "set" }
    },
    "selection": {
        "candidate_count": 5,
        "allowed_question_types": [],
        "required_target_ids": ["<string>"],
        "excluded_question_ids": ["<string>"]
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    state_version: 1,
    previous_turn: {
      decision_id: '<string>',
      question_id: '<string>',
      assistant_text: '<string>',
      user_text: '<string>',
      message_id: '<string>'
    },
    context_update: {mode: 'summary', text: '<string>'},
    client_updates: {
      data: [{id: '<string>', value: '<string>', operation: 'set'}],
      dimensions: [{id: '<string>', operation: 'set'}],
      objective: {operation: 'set'}
    },
    selection: {
      candidate_count: 5,
      allowed_question_types: [],
      required_target_ids: ['<string>'],
      excluded_question_ids: ['<string>']
    }
  })
};

fetch('https://api.zelinqa.ai/v1/sessions/{session_id}/next', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "session_id": "<string>",
  "decision_id": "<string>",
  "action": "ask",
  "stop_reason": "no_question_available",
  "candidates": [
    {
      "rank": 5,
      "question_id": "<string>",
      "text": "<string>",
      "type": "open",
      "choices": [
        {
          "choice_id": "<string>",
          "label": "<string>"
        }
      ],
      "target_ids": [
        "<string>"
      ],
      "selection_mode": "single"
    }
  ],
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0.5,
      "client_override": {
        "status": "achieved",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "effective_status": "not_started"
    },
    "dimensions": [
      {
        "id": "<string>",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0.5,
        "client_override": {
          "status": "achieved",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "effective_status": "not_started"
      }
    ]
  },
  "turn_count": 1,
  "turns_remaining": 1,
  "warnings": [
    "objective_achieved"
  ],
  "degraded": true,
  "degraded_reasons": [
    "missing_user_text"
  ],
  "versions": {
    "state_version": 1,
    "engine_version": "<string>",
    "api_version": "1.0"
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "invalid_previous_turn",
  "message": "An answered open question requires user_text.",
  "request_id": "req_open_without_text",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

POST

sessions

{session_id}

Get the next questions

curl --request POST \
  --url https://api.zelinqa.ai/v1/sessions/{session_id}/next \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "state_version": 1,
  "previous_turn": {
    "decision_id": "<string>",
    "question_id": "<string>",
    "assistant_text": "<string>",
    "user_text": "<string>",
    "message_id": "<string>"
  },
  "context_update": {
    "mode": "summary",
    "text": "<string>"
  },
  "client_updates": {
    "data": [
      {
        "id": "<string>",
        "value": "<string>",
        "operation": "set"
      }
    ],
    "dimensions": [
      {
        "id": "<string>",
        "operation": "set"
      }
    ],
    "objective": {
      "operation": "set"
    }
  },
  "selection": {
    "candidate_count": 5,
    "allowed_question_types": [],
    "required_target_ids": [
      "<string>"
    ],
    "excluded_question_ids": [
      "<string>"
    ]
  }
}
'

import requests

url = "https://api.zelinqa.ai/v1/sessions/{session_id}/next"

payload = {
    "state_version": 1,
    "previous_turn": {
        "decision_id": "<string>",
        "question_id": "<string>",
        "assistant_text": "<string>",
        "user_text": "<string>",
        "message_id": "<string>"
    },
    "context_update": {
        "mode": "summary",
        "text": "<string>"
    },
    "client_updates": {
        "data": [
            {
                "id": "<string>",
                "value": "<string>",
                "operation": "set"
            }
        ],
        "dimensions": [
            {
                "id": "<string>",
                "operation": "set"
            }
        ],
        "objective": { "operation": "set" }
    },
    "selection": {
        "candidate_count": 5,
        "allowed_question_types": [],
        "required_target_ids": ["<string>"],
        "excluded_question_ids": ["<string>"]
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    state_version: 1,
    previous_turn: {
      decision_id: '<string>',
      question_id: '<string>',
      assistant_text: '<string>',
      user_text: '<string>',
      message_id: '<string>'
    },
    context_update: {mode: 'summary', text: '<string>'},
    client_updates: {
      data: [{id: '<string>', value: '<string>', operation: 'set'}],
      dimensions: [{id: '<string>', operation: 'set'}],
      objective: {operation: 'set'}
    },
    selection: {
      candidate_count: 5,
      allowed_question_types: [],
      required_target_ids: ['<string>'],
      excluded_question_ids: ['<string>']
    }
  })
};

fetch('https://api.zelinqa.ai/v1/sessions/{session_id}/next', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "session_id": "<string>",
  "decision_id": "<string>",
  "action": "ask",
  "stop_reason": "no_question_available",
  "candidates": [
    {
      "rank": 5,
      "question_id": "<string>",
      "text": "<string>",
      "type": "open",
      "choices": [
        {
          "choice_id": "<string>",
          "label": "<string>"
        }
      ],
      "target_ids": [
        "<string>"
      ],
      "selection_mode": "single"
    }
  ],
  "progress": {
    "objective": {
      "computed_status": "not_started",
      "progress": 0.5,
      "client_override": {
        "status": "achieved",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "effective_status": "not_started"
    },
    "dimensions": [
      {
        "id": "<string>",
        "order_position": 1,
        "completion_role": "blocking",
        "computed_status": "not_started",
        "progress": 0.5,
        "client_override": {
          "status": "achieved",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "effective_status": "not_started"
      }
    ]
  },
  "turn_count": 1,
  "turns_remaining": 1,
  "warnings": [
    "objective_achieved"
  ],
  "degraded": true,
  "degraded_reasons": [
    "missing_user_text"
  ],
  "versions": {
    "state_version": 1,
    "engine_version": "<string>",
    "api_version": "1.0"
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

{
  "code": "invalid_previous_turn",
  "message": "An answered open question requires user_text.",
  "request_id": "req_open_without_text",
  "details": {}
}

{
  "code": "unauthorized",
  "message": "<string>",
  "request_id": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Send the domain-scoped API key as Authorization: Bearer . Never send client-supplied identity headers.

Headers

Idempotency-Key

string

required

Unique key per logical mutation; reuse the same key and body when retrying after a timeout.

Required string length: 8 - 128

Path Parameters

session_id

string

required

Server-issued session ID in the path.

Required string length: 1 - 128

Body

application/json

state_version

integer

required

Session state version last read by the client; used for optimistic concurrency.

Required range: x >= 0

previous_turn

object

Observation of the preceding exchange; omit on the first call of a new session. Decision and question IDs are optional aids, never IDs to invent. For an answered open question, non-blank user_text is required unless outcome is explicitly asked_no_answer or refused; otherwise the API returns 422 invalid_previous_turn before model analysis. Closed and semi-open questions accept choice_ids alone; semi-open questions may also include free_text. Context and client updates do not replace a required reply.

Show child attributes

context_update

object

Context added since the preceding call, as either a compact summary or an ordered message delta.

Option 1
Option 2

Show child attributes

client_updates

object

Confirmed data or progress explicitly supplied by the integrating application.

Show child attributes

selection

object

Constraints for this call, applied before ranking rather than after candidate selection.

Show child attributes

Response

Successful response.

A ranked decision, not a raw selection score. action=ask has a decision ID, a null stop reason, and at least one candidate. action=stop has a stop reason, a null decision ID, and no candidates.

request_id

string

required

session_id

string

required

decision_id

string | null

required

Present for action=ask; send it with the next observed turn when available.

action

enum<string>

required

stop when the session reached max_turns or no identifiable question remains; an achieved objective emits a warning instead.

Available options:

ask,

stop

stop_reason

enum<string> | null

required

Stop reason: max_turns_reached when the session reached its turn limit, or no_question_available when no question remains after hard exclusions.

Available options:

no_question_available,

max_turns_reached

candidates

object[]

required

Ranked from most to least relevant; multiple candidates avoid covering the same information twice.

Maximum array length: 10

Show child attributes

progress

object

required

Show child attributes

turn_count

integer

required

Required range: x >= 0

turns_remaining

integer

required

Zero when the turn limit is reached; action is then stop.

Required range: x >= 0

warnings

enum<string>[]

required

Business signals that do not stop the conversation: objective_achieved, eligibility_exhausted_fallback, or constraints_relaxed.

Available options:

objective_achieved,

eligibility_exhausted_fallback,

constraints_relaxed

degraded

boolean

required

True when understanding this turn used a reduced mode; the decision remains usable.

degraded_reasons

enum<string>[]

required

Available options:

missing_user_text,

summary_only_context,

semantic_service_unavailable,

unresolved_previous_turn

versions

object

required

Public engine and API versions plus the session state version. The session's pinned configuration version is not exposed or client-selectable.

Show child attributes

API guides

Sessions

Configuration

Service

Get the next questions

Authorizations

Headers

Path Parameters

Body

Response