Informations de base

Propriété	Valeur
URL de base	`/api/v3/conversation`
Authentification	Clé API avec le scope `ayeto.conversation`
Limite de débit	Limites par défaut

Authentification

Clé API

Tous les endpoints nécessitent une clé API avec la permission (scope) ayeto.conversation.

En-tête d’authentification

uni-api-key: <YOUR_API_KEY>

Format de la clé API

La clé API a le format suivant :

ayeto-{64_caractères_hexadécimaux_aléatoires}

Exemple :

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Scopes

Pour utiliser les endpoints de conversation, la clé API doit avoir l’un des scopes suivants : - ayeto.conversation - scope spécifique aux conversations - * - scope générique (accès à tous les endpoints)

Réponses d’erreur d’authentification

Erreur	Description
`API key not provided`	L’en-tête `uni-api-key` est manquant ou vide.
`API key is invalid`	La clé API n’existe pas, est désactivée ou n’a pas le scope requis.

Endpoints disponibles

Endpoint	Méthode	Description
`/api/v3/conversation/find`	POST	Rechercher des conversations
`/api/v3/conversation/get`	POST	Obtenir une seule conversation
`/api/v3/conversation/delete`	POST	Supprimer une conversation

Modèle de réponse - `PublicConversationView`

Tous les endpoints renvoient les conversations dans ce format :

Champ	Type	Description
`id`	`UUID`	Identifiant unique de la conversation.
`name`	`string`	Nom de la conversation.
`model`	`string`	ID du modèle LLM utilisé.
`img_gen_model`	`string`	ID du modèle de génération d’image.
`summary`	`string`	Résumé de la conversation (s’il est généré).
`organization_id`	`UUID \\| null`	ID de l’organisation (si la conversation est dans un contexte organisationnel).
`assistant_id`	`UUID \\| null`	ID de l’assistant (si un assistant a été utilisé).
`messages`	`BasicLLMMessageView[]`	Liste des messages de la conversation.
`created`	`ModelMeta`	Métadonnées de création.
`updated`	`ModelMeta`	Métadonnées de la dernière mise à jour.
`accessed`	`ModelMeta`	Métadonnées du dernier accès.

Modèle de message - `BasicLLMMessageView`

Champ	Type	Description
`id`	`UUID`	Identifiant unique du message.
`timestamp`	`integer`	Horodatage Unix de création du message (en millisecondes).
`role`	`string`	Rôle du message : `system`, `user`, `assistant`, `tool`, `internal`.
`content`	`string \\| null`	Contenu textuel du message.
`reasoning_content`	`string \\| null`	Contenu du raisonnement (si le modèle le prend en charge).
`model`	`string \\| null`	ID du modèle utilisé pour ce message.
`img_gen`	`ImgGenMessage \\| null`	Données d’image générée.

ModelMeta

Champ	Type	Description
`user_id`	`UUID \\| null`	ID de l’utilisateur ayant effectué l’action.
`timestamp`	`integer`	Horodatage Unix de l’action (en millisecondes).

POST /api/v3/conversation/find

Rechercher des conversations avec prise en charge du filtrage, du tri et de la pagination.

Corps de la requête - `DbParams`

Les paramètres sont transmis en JSON dans le corps de la requête :

Paramètre	Type	Obligatoire	Description
`sort_key`	`string`	Non	Champ de tri (par ex. `updated.timestamp`, `name`).
`sort_order`	`integer`	Non	Direction du tri : `0` = ASC, `1` = DESC.
`limit_from`	`integer`	Non	Index de départ pour la pagination.
`limit_to`	`integer`	Non	Index de fin pour la pagination.
`filters`	`array`	Non	Tableau de filtres.

Filtres

Les filtres sont transmis comme un tableau de conditions :

["field", "operator", "value"]

Opérateurs pris en charge

Opérateur	Description
`==`	Égal à
`!=`	Différent de
`<`	Inférieur à
`>`	Supérieur à
`<=`	Inférieur ou égal à
`>=`	Supérieur ou égal à
`regex`	Expression régulière

Exemples de filtres

["name", "regex", ".*test.*"]
["model", "==", "gpt-4o"]
["updated.timestamp", ">", 1735815581000]
["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]

Réponse

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Ma conversation",
    "model": "gpt-4o",
    "img_gen_model": "dall-e-3",
    "summary": "Discussion sur la programmation Python...",
    "organization_id": null,
    "assistant_id": null,
    "messages": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "timestamp": 1735815581000,
        "role": "user",
        "content": "Bonjour, comment écrire une fonction en Python ?",
        "reasoning_content": null,
        "model": null,
        "img_gen": null
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "timestamp": 1735815582000,
        "role": "assistant",
        "content": "Vous définissez une fonction en Python à l’aide du mot-clé `def`...",
        "reasoning_content": null,
        "model": "gpt-4o",
        "img_gen": null
      }
    ],
    "created": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815580000
    },
    "updated": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815582000
    },
    "accessed": {
      "user_id": null,
      "timestamp": 0
    }
  }
]

POST /api/v3/conversation/get

Obtenir une seule conversation par son ID.

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`entity_id`	`UUID`	Oui	ID de la conversation.

Réponse

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Ma conversation",
  "model": "gpt-4o",
  "img_gen_model": "dall-e-3",
  "summary": "",
  "organization_id": null,
  "assistant_id": null,
  "messages": [...],
  "created": {...},
  "updated": {...},
  "accessed": {...}
}

POST /api/v3/conversation/delete

Supprimer une conversation par son ID.

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`entity_id`	`UUID`	Oui	ID de la conversation à supprimer.

Réponse

Renvoie l’UUID de la conversation supprimée :

"550e8400-e29b-41d4-a716-446655440000"

Exemples cURL

1. Obtenir toutes les conversations

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{}'

2. Obtenir les conversations avec tri (les plus récentes d’abord)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1
  }'

3. Obtenir les conversations avec pagination (les 10 premières)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 10
  }'

4. Obtenir les conversations avec un filtre (par modèle)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["model", "==", "gpt-4o"]]
  }'

5. Obtenir les conversations avec un filtre (par nom - regex)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["name", "regex", ".*Python.*"]]
  }'

6. Obtenir les conversations pour un assistant spécifique

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]]
  }'

7. Obtenir les conversations plus récentes qu’une date spécifique

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["created.timestamp", ">", 1735689600000]]
  }'

8. Combiner plusieurs filtres

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20,
    "filters": [
      ["model", "==", "gpt-4o"],
      ["created.timestamp", ">", 1735689600000]
    ]
  }'

9. Obtenir une seule conversation par son ID

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/get?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

10. Supprimer une conversation

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/delete?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

11. cURL verbeux pour le débogage

curl -v -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_from": 0,
    "limit_to": 5
  }'

États d’erreur

Statut HTTP	Description
`400`	Requête incorrecte (paramètres invalides, format de filtre incorrect).
`401`	Clé API invalide ou manquante (en-tête `uni-api-key`).
`403`	Permissions insuffisantes (l’utilisateur n’a pas accès à la conversation).
`404`	Conversation introuvable.
`500`	Erreur interne du serveur.

Exemple de réponse d’erreur

{
  "detail": "not found, id: 550e8400-e29b-41d4-a716-446655440000"
}

Notes

Permissions : L’utilisateur ne peut voir que ses propres conversations (les conversations qu’il a créées).
Filtres : Plusieurs filtres dans le tableau sont appliqués avec une condition AND.
Pagination : Pour un grand nombre de conversations, nous recommandons d’utiliser limit_from et limit_to.
Tri : Le tri par défaut n’est pas défini ; nous recommandons de spécifier explicitement sort_key et sort_order.
Horodatage : Tous les horodatages sont en millisecondes (Unix epoch * 1000).

Informations de base

Authentification

Clé API

En-tête d’authentification

Format de la clé API

Scopes

Réponses d’erreur d’authentification

Endpoints disponibles

Modèle de réponse - PublicConversationView

Modèle de message - BasicLLMMessageView

ModelMeta

POST /api/v3/conversation/find

Corps de la requête - DbParams

Filtres

Opérateurs pris en charge

Exemples de filtres

Réponse

POST /api/v3/conversation/get

Paramètres de requête

Réponse

POST /api/v3/conversation/delete

Paramètres de requête

Réponse

Exemples cURL

1. Obtenir toutes les conversations

2. Obtenir les conversations avec tri (les plus récentes d’abord)

3. Obtenir les conversations avec pagination (les 10 premières)

4. Obtenir les conversations avec un filtre (par modèle)

5. Obtenir les conversations avec un filtre (par nom - regex)

6. Obtenir les conversations pour un assistant spécifique

7. Obtenir les conversations plus récentes qu’une date spécifique

8. Combiner plusieurs filtres

9. Obtenir une seule conversation par son ID

10. Supprimer une conversation

11. cURL verbeux pour le débogage

États d’erreur

Exemple de réponse d’erreur

Notes

Modèle de réponse - `PublicConversationView`

Modèle de message - `BasicLLMMessageView`

Corps de la requête - `DbParams`