Conversations

Une conversation est l'historique enregistré d'un chat : les messages échangés avec un modèle ou un assistant, son nom et quelques liens (assistant, organisation, tâche, exécution de workflow). Les conversations sont créées par l'endpoint chat ; il n'existe pas d'endpoint pour en créer ou en modifier une directement. Pour poursuivre une conversation, envoyez son id comme conversation_id à chat.

Les quatre endpoints ne voient que les conversations de l'utilisateur de la clé API :

• les conversations que l'utilisateur a démarrées dans l'application ou via l'API, à titre personnel et dans toute organisation à laquelle il appartient ;
• les conversations démarrées pour le compte de l'utilisateur par des tâches planifiées et des exécutions de workflows.

Les conversations des autres utilisateurs ne sont jamais renvoyées, même lorsqu'elles appartiennent à la même organisation ou qu'elles sont partagées publiquement par un lien. Une conversation qui existe mais qui ne vous appartient pas est signalée comme introuvable.

Le coût d'une conversation est disponible via l'endpoint de coût d'utilisation.

Lister les conversations #

Renvoie les conversations de l'utilisateur qui correspondent aux filtres, les plus récentes en premier, sauf si vous triez autrement. Chaque conversation est renvoyée avec l'intégralité de son historique de messages : paginez donc toujours les résultats.

Requête #

Le corps est un objet de requête avec les champs habituels de filtres, tri et pagination. Envoyez {} pour tout obtenir ; le corps lui-même est obligatoire.

Pour tout lire, demandez des pages jusqu'à ce qu'une page revienne plus courte que demandé. Le total pour une pagination s'obtient avec compter les conversations.

Filtres utiles #

Les filtres peuvent porter sur n'importe quel champ de la conversation, y compris les champs des messages (messages.content, messages.role, messages.model). Les conditions sur les messages sont vérifiées sur chaque message enregistré, y compris les résultats d'outils et les autres messages qui ne sont pas renvoyés dans messages.

Les filtres textuels sont comparés au texte enregistré après que l'API a échappé <, >, " et ' : une valeur de filtre contenant ces caractères correspond donc rarement ; voir filtres.

Réponse #

200 OK avec un tableau de conversations.

Erreurs #

Les erreurs d'authentification, de limite de débit et de serveur sont décrites dans les conventions.

Exemple #

Les 20 conversations avec un assistant donné mises à jour le plus récemment :

curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["assistant_id", "==", "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"]],
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20
  }'

[
  {
    "id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
    "name": "Delivery terms for order 1042",
    "model": "gpt-5",
    "summary": "",
    "organization_id": null,
    "assistant_id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90",
    "task_id": null,
    "task_execution_id": null,
    "workflow_id": null,
    "workflow_run_id": null,
    "public_sharing": false,
    "messages": [
      {
        "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "timestamp": 1759395601000,
        "role": "user",
        "content": "What delivery date did we agree for order 1042?",
        "reasoning_content": null,
        "model": null,
        "attachments": [],
        "tool_runs": {}
      },
      {
        "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
        "timestamp": 1759395606000,
        "role": "assistant",
        "content": "The agreed delivery date for order 1042 is 14 October 2026.",
        "reasoning_content": null,
        "model": "gpt-5",
        "attachments": [],
        "tool_runs": {}
      }
    ],
    "created": {"timestamp": 1759395600000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"},
    "updated": {"timestamp": 1759395606000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"},
    "accessed": {"timestamp": 1759395606000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"}
  }
]

Compter les conversations #

Renvoie le nombre de conversations de l'utilisateur qui correspondent aux filtres, voir comptage.

Requête #

Le même objet de requête que pour lister les conversations ; envoyez {} pour les compter toutes. Seul filters est utilisé : limit_from, limit_to et les champs de tri sont ignorés, vous pouvez donc envoyer le même corps que pour la page que vous affichez.

Réponse #

200 OK avec le nombre de conversations correspondantes sous forme d'entier JSON.

42

Erreurs #

Les erreurs d'authentification, de limite de débit et de serveur sont décrites dans les conventions.

Exemple #

Conversations avec un assistant donné modifiées depuis un instant donné :

curl -X POST "https://ayeto.ai/api/v3/conversation/count" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      ["assistant_id", "==", "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"],
      ["updated.timestamp", ">=", 1759363200000]
    ]
  }'

7

Obtenir une conversation #

Renvoie une conversation avec l'intégralité de son historique de messages.

Requête #

L'id peut aussi être envoyé à la place dans le paramètre de requête entity_id, sans corps ou avec {} ; voir paramètres.

Lire une conversation compte comme l'ouvrir : son horodatage accessed est mis à jour (au plus une fois par minute).

Réponse #

200 OK avec une conversation.

Erreurs #

Exemple #

curl -X POST "https://ayeto.ai/api/v3/conversation/get" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"}'

La réponse est un objet unique de même forme qu'un élément de l'exemple de liste.

Supprimer une conversation #

Supprime définitivement une conversation, ainsi que les fichiers qui lui appartiennent (pièces jointes qui y ont été envoyées et images ou autres fichiers qui y ont été générés). Cette opération est irréversible.

Requête #

L'id peut aussi être envoyé à la place dans le paramètre de requête entity_id, sans corps ou avec {} ; voir paramètres.

Réponse #

200 OK avec l'id de la conversation supprimée sous forme de chaîne JSON.

"8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"

Erreurs #

Exemple #

curl -X POST "https://ayeto.ai/api/v3/conversation/delete" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"}'

Conversation #

L'objet renvoyé par tous les endpoints de conversation.

Message #

Pièce jointe #

Appels d'outils dans le contenu des messages #

Chaque outil appelé par le modèle pendant la rédaction d'un message de l'assistant apparaît dans content sous la forme d'un bloc qui commence par "\n\n### calling AI tool ...\n" et se termine par "\n***\n". Le texte entre les deux marqueurs est la sortie de l'outil affichée à l'utilisateur :

{
  "role": "assistant",
  "content": "Let me look that up.\n\n### calling AI tool ...\nSearching the web for \"order 1042 delivery\"...\n***\nThe agreed delivery date is 14 October 2026."
}

Retirez ces blocs si vous n'avez besoin que du texte de la réponse. (L'endpoint chat peut les omettre de sa propre réponse avec remove_tool_calls ; la conversation enregistrée les conserve toujours.)

Lorsqu'un assistant appelle un autre assistant comme outil, la réponse de cet assistant est enregistrée dans tool_runs, avec pour clé la position de l'appel d'outil dans content, sous forme de chaîne ("0" pour le premier appel d'outil, "1" pour le deuxième, et ainsi de suite). Chaque valeur contient une chaîne content au même format et ses propres tool_runs imbriqués.