curl --request POST \
--url https://api.zelinqa.ai/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '{}'{
"request_id": "req_1001",
"session_id": "ses_01J8Z",
"client_reference": "crm-lead-8842",
"status": "active",
"turn_count": 0,
"max_turns": 15,
"turns_remaining": 15,
"question_state": {
"outcomes": []
},
"targets": {},
"progress": {
"objective": {
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
"dimensions": [
{
"id": "so_besoin",
"order_position": 0,
"completion_role": "blocking",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
{
"id": "so_budget",
"order_position": 1,
"completion_role": "blocking",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
{
"id": "so_livraison",
"order_position": 2,
"completion_role": "contributing",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
}
]
},
"pending_decision": null,
"degraded": false,
"versions": {
"state_version": 0,
"engine_version": "1.0.0",
"api_version": "1.0"
}
}{
"code": "unauthorized",
"message": "Clé d'intégration absente ou invalide.",
"request_id": "req_9000",
"details": {}
}{
"code": "insufficient_scope",
"message": "Cette clé ne permet pas de publier une configuration.",
"request_id": "req_9001",
"details": {
"required_scopes": [
"configuration:publish"
],
"granted_scopes": [
"configuration:read",
"configuration:write"
]
}
}{
"code": "idempotency_key_reused",
"message": "Cette clé d'idempotence est déjà associée à une autre requête.",
"request_id": "req_9002",
"details": {
"idempotency_key": "create-session-8842"
}
}{
"code": "compiled_artifact_unavailable",
"message": "L'artefact moteur de cette session est temporairement indisponible.",
"request_id": "req_9010",
"details": {
"session_id": "ses_01J8Z"
}
}{
"code": "invalid_choice",
"message": "La valeur fournie n'est pas valide pour cette information de réussite.",
"request_id": "req_9014",
"details": {
"data_id": "delivery_window",
"invalid_value": "dans_deux_ans"
}
}{
"code": "idempotency_contention",
"message": "La clé d'idempotence n'a pas pu être réservée, réessayez.",
"request_id": "req_9017",
"details": {
"idempotency_key": "next-ses01J8Z-turn-4",
"retry_after_seconds": 1
}
}Créer une session
Crée une session attachée à la version publiée active. La première question est obtenue ensuite avec POST /v1/sessions//next. initial_history permet de reprendre une conversation déjà commencée.
curl --request POST \
--url https://api.zelinqa.ai/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '{}'{
"request_id": "req_1001",
"session_id": "ses_01J8Z",
"client_reference": "crm-lead-8842",
"status": "active",
"turn_count": 0,
"max_turns": 15,
"turns_remaining": 15,
"question_state": {
"outcomes": []
},
"targets": {},
"progress": {
"objective": {
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
"dimensions": [
{
"id": "so_besoin",
"order_position": 0,
"completion_role": "blocking",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
{
"id": "so_budget",
"order_position": 1,
"completion_role": "blocking",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
},
{
"id": "so_livraison",
"order_position": 2,
"completion_role": "contributing",
"computed_status": "not_started",
"progress": 0,
"client_override": null,
"effective_status": "not_started"
}
]
},
"pending_decision": null,
"degraded": false,
"versions": {
"state_version": 0,
"engine_version": "1.0.0",
"api_version": "1.0"
}
}{
"code": "unauthorized",
"message": "Clé d'intégration absente ou invalide.",
"request_id": "req_9000",
"details": {}
}{
"code": "insufficient_scope",
"message": "Cette clé ne permet pas de publier une configuration.",
"request_id": "req_9001",
"details": {
"required_scopes": [
"configuration:publish"
],
"granted_scopes": [
"configuration:read",
"configuration:write"
]
}
}{
"code": "idempotency_key_reused",
"message": "Cette clé d'idempotence est déjà associée à une autre requête.",
"request_id": "req_9002",
"details": {
"idempotency_key": "create-session-8842"
}
}{
"code": "compiled_artifact_unavailable",
"message": "L'artefact moteur de cette session est temporairement indisponible.",
"request_id": "req_9010",
"details": {
"session_id": "ses_01J8Z"
}
}{
"code": "invalid_choice",
"message": "La valeur fournie n'est pas valide pour cette information de réussite.",
"request_id": "req_9014",
"details": {
"data_id": "delivery_window",
"invalid_value": "dans_deux_ans"
}
}{
"code": "idempotency_contention",
"message": "La clé d'idempotence n'a pas pu être réservée, réessayez.",
"request_id": "req_9017",
"details": {
"idempotency_key": "next-ses01J8Z-turn-4",
"retry_after_seconds": 1
}
}Autorisations
En-têtes
Clé unique par mutation logique, choisie par l'appelant.
Même clé et même corps renvoient exactement la réponse d'origine, sans
rejouer l'effet : aucun retry ne double turn_count, un outcome, un
événement, un feedback ou une publication. Même clé avec un corps différent
produit 409 idempotency_key_reused.
Les enregistrements sont isolés par tenant et par opération, et sont purgés après 24 heures. Passé ce délai, la même clé est traitée comme neuve.
8 - 128Corps
Le client ne choisit ni la version de configuration, ni une politique d'accusé de réception : la session épingle en interne la version publiée active au moment de sa création.
Surcharge la limite de tours définie dans la configuration. Une fois cette
limite atteinte, /next répond action: stop avec
stop_reason: max_turns_reached. La valeur peut être ramenée au
plafond du plan du compte ; la valeur effective se lit dans max_turns et
turns_remaining de la réponse.
1 <= x <= 100Réponse
Session créée.