Référence de l'API · Sessions et messages

API des sessions de chat et des messages

Créer, lister, renommer, épingler, marquer comme favori et supprimer des sessions de chat, et gérer les messages individuels qu'elles contiennent — y compris l'historique des modifications suivi et l'annulation.

← Retour à la documentation Aller aux points de terminaison

Points de terminaison de session

POST /api/v1/sessions

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}/messages

PATCH /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

Points de terminaison de messages

GET /api/v1/messages/{message_id}

PATCH /api/v1/messages/{message_id}

GET /api/v1/messages/{message_id}/history

POST /api/v1/messages/{message_id}/undo

DELETE /api/v1/messages/{message_id}

Créer une session — Corps de la requête

json

{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id n'est pas accepté depuis le client dans le runtime personnel, et doit correspondre au contexte d'exécution actif de l'espace de travail sinon — il n'est jamais pris comme une substitution arbitraire fournie par le client.

Lister — Paramètres de requête et réponse

kindagent_idpinnedlimit (par défaut 50, max 200)offset (par défaut 0)

json

{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Mettre à jour la session (PATCH)

Au moins un champ doit être présent dans le corps de la requête — un PATCH vide est rejeté.

titlepinnedstarredmarked_unread

json

{
  "pinned": true,
  "starred": false
}

Comportements de session

Une session appartient exactement à un seul propriétaire (un utilisateur, éventuellement associé à un espace de travail) — déterminé par le contexte de la requête authentifiée, et non par les données fournies par le client.
La suppression d'une session est une suppression logique (deleted_at est défini) ; la session et ses messages restent dans la base de données mais sont exclus de toutes les requêtes standard.
GET /sessions/{session_id}/messages renvoie un décompte de messages calculé en temps réel à partir des messages eux-mêmes, et non un compteur mis en cache.
Les paramètres de chemin session_id et message_id sont validés en tant qu'UUID — un ID malformé renvoie une erreur de validation claire, et non une erreur serveur.
Les sessions de démonstration du site marketing sont limitées à 3 par utilisateur et renvoient 403 une fois cette limite atteinte.

Historique des modifications des messages et annulation

Chaque modification du contenu ou de la charge utile d'un message est enregistrée avant l'application du changement, préservant la version précédente.

json

[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]

Un message ne peut être modifié ou supprimé que par le propriétaire de la session à laquelle il appartient.
Undo restaure la version enregistrée la plus récente et supprime cette entrée d'historique — cela ne revient pas au-delà de la dernière modification.
La modification ou la suppression d'un message n'ajuste pas actuellement le champ de décompte mis en cache de la session ; il reflète toujours le décompte en direct.

Modèles d'erreur

400

Requête invalide — notamment un corps PATCH vide ou l'absence de modifications détectées.

401

Authentification manquante ou invalide.

404

Session ou message introuvable (ou n'appartenant pas à l'appelant).

Exemples

Créer une session

bash

curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Épingler une session

bash

curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Modifier un message

bash

curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Annuler la dernière modification

bash

curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"