HTTP calls with curl - Zelinqa

This guide covers direct HTTP integrations. To start with the official SDKs, use the quickstart. You need a published configuration and a key with the runtime scope.

1. Create a session

curl --request POST 'https://api.zelinqa.ai/v1/sessions' \
  --header "Authorization: Bearer $ZELINQA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: session-$(uuidgen)" \
  --data '{
    "client_reference": "lead-8842",
    "max_turns": 10
  }'

Keep the returned session_id and versions.state_version. A new session starts at version 0.

2. Obtain the first question

export ZELINQA_SESSION_ID="ses_01J8Z"

curl --request POST "https://api.zelinqa.ai/v1/sessions/$ZELINQA_SESSION_ID/next" \
  --header "Authorization: Bearer $ZELINQA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: next-$(uuidgen)" \
  --data '{"state_version": 0}'

When action is ask, display or rephrase candidates[0]. Keep the new versions.state_version and, when possible, the decision_id.

3. Send the visitor answer

curl --request POST "https://api.zelinqa.ai/v1/sessions/$ZELINQA_SESSION_ID/next" \
  --header "Authorization: Bearer $ZELINQA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: next-$(uuidgen)" \
  --data '{
    "state_version": 1,
    "previous_turn": {
      "decision_id": "dec_7f2a",
      "question_id": "q_budget",
      "assistant_text": "What budget would you like to allocate to the project?",
      "user_text": "Around 2,000 euros.",
      "message_id": "msg_18"
    }
  }'

Always use the state_version you actually received; 1 is illustrative here.

4. Record the final outcome

curl --request POST "https://api.zelinqa.ai/v1/sessions/$ZELINQA_SESSION_ID/feedback" \
  --header "Authorization: Bearer $ZELINQA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: feedback-$(uuidgen)" \
  --data '{
    "result": "success",
    "label": "lead_qualified"
  }'

Find complete schemas, examples, and errors in the API reference.