Conversations

3 endpoints

get/v1/conversations

Lister les conversations

Retourne la liste paginée des conversations (threads de chat) du client (cursor v2). Tri stable created_at DESC, id DESC.

Une conversation agrège les messages d'un visiteur avec un agent (IA ou humain) sous le client appelant. La création de threads et l'envoi de messages se font côté front-end / SDK chat — l'API publique expose la lecture seule.

Filtres

?agent_slug — filtre exact sur l'agent IA répondant dans le thread.
?source — filtre exact sur la source du thread (URL, label de funnel, widget, etc.).

Scopes requis: conversations:read

Paramètres de requête

Nom	Type	obligatoire	Description
`agent_slug`	`string`	optionnel	Slug de l'agent IA — filtre exact sur les threads servis par cet agent.
`source`	`string`	optionnel	Source du thread — filtre exact (URL, label de funnel, `widget`, etc.).

Responses

Status	Description
`200`	Liste paginée des conversations.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/conversations' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

get/v1/conversations/{id}

Récupérer une conversation

Retourne les méta-données d'une conversation par son ID. Pour récupérer les messages individuels, utiliser GET /v1/conversations/{id}/messages.

Si la conversation appartient à un autre client (ou n'existe pas), retourne 404 resource_not_found — l'isolation tenant masque l'existence des conversations hors du client appelant.

Scopes requis: conversations:read

Responses

Status	Description
`200`	Conversation trouvée.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/conversations/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

get/v1/conversations/{id}/messages

Lister les messages d'une conversation

Retourne la liste paginée des messages d'une conversation en ordre chronologique de lecture (created_at ASC, id ASC), avec un tiebreaker id pour éviter les doublons ou skips entre deux pages quand plusieurs messages partagent la même milliseconde.

Cette direction de tri (ASC) est inversée par rapport aux autres list endpoints v2 (DESC) — la lecture naturelle d'une conversation suit l'ordre chronologique des échanges.

Si la conversation appartient à un autre client (ou n'existe pas), retourne 404 resource_not_found.

Scopes requis: conversations:read

Responses

Status	Description
`200`	Liste paginée des messages (ordre chronologique).
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/conversations/{id}/messages' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'