Conventions

Cette page décrit les règles que suit chaque endpoint de l'API d'intégration. Les pages des endpoints ne mentionnent que les cas où un endpoint s'en écarte.

Requêtes #

L'API est de type RPC sur HTTP POST, et non REST. Les endpoints sont des requêtes POST vers un chemin qui nomme l'action, par exemple :

Il n'existe aucun endpoint PUT, PATCH ou DELETE ni aucun identifiant de ressource dans le chemin ; l'identifiant d'un enregistrement est un paramètre. Chaque endpoint accepte POST. Deux endpoints en lecture seule sans paramètres, solde de crédits et version, répondent aussi à GET pour la compatibilité avec les anciens clients ; utilisez POST dans le nouveau code.

L'URL de base est :

https://ayeto.ai/api/v3

En-têtes #

L'en-tête language indique au modèle dans le chat la langue dans laquelle l'utilisateur écrit et sélectionne la langue des textes traduits que renvoient certains endpoints (par exemple les noms des outils dans modèles et outils). Les messages d'erreur sont toujours en anglais.

L'en-tête ne s'applique qu'à cette requête. Il ne modifie jamais la langue que l'utilisateur a choisie dans l'application AYETO, et qu'AYETO utilise pour les e-mails de l'utilisateur et les tâches planifiées.

Paramètres #

Les paramètres sont envoyés dans le corps JSON, sauf indication contraire sur la page de l'endpoint. Les endpoints qui agissent sur un seul enregistrement par identifiant (.../get, .../delete) prennent l'identifiant dans le corps sous la forme {"id": "<uuid>"} :

curl -X POST "https://ayeto.ai/api/v3/conversation/get" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90"}'

Ils acceptent aussi l'identifiant dans le paramètre de requête entity_id, comme l'exigeaient les versions antérieures de l'API ; le corps peut alors être omis ou valoir {}. Un corps que vous envoyez doit être du JSON avec Content-Type: application/json, comme pour tout endpoint :

curl -X POST "https://ayeto.ai/api/v3/conversation/get?entity_id=0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90" \
  -H "uni-api-key: $AYETO_API_KEY"

Une requête sans aucun des deux, avec les deux définis sur des identifiants différents, ou avec un id qui n'est pas un UUID est rejetée avec 422.

Un endpoint dont les paramètres sont un objet JSON exige un corps, même si vous voulez toutes les valeurs par défaut : envoyez {}. Une requête sans corps est rejetée avec 422.

Valeurs #

• Les identifiants sont des UUID, écrits sous forme de chaînes : "0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90". Les réponses utilisent toujours la forme en minuscules avec tirets.
• Les horodatages sont des entiers : des millisecondes depuis l'epoch Unix (UTC), par exemple 1790846045000 pour 2026-10-01 09:14:05 UTC. 0 signifie « jamais ».

Réponses #

Une requête réussie renvoie 200 avec un corps JSON : un objet, un tableau d'objets (endpoints find), un nombre (endpoints count) ou l'identifiant de l'enregistrement concerné sous forme de chaîne JSON (endpoints delete). Les endpoints en streaming renvoient un stream à la place. Les erreurs sont décrites dans Erreurs.

Champs communs #

Chaque enregistrement stocké que renvoie l'API (une conversation, un assistant, un workflow, une exécution de workflow, ...) porte son identifiant et trois objets de métadonnées :

Chaque objet de métadonnées a la même forme :

{
  "id": "0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90",
  "created": { "timestamp": 1790846045000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" },
  "updated": { "timestamp": 1790846052000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" },
  "accessed": { "timestamp": 1790846052000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" }
}

La plupart des endpoints renvoient une vue publique de l'enregistrement : ces champs plus les champs listés sur la page de l'endpoint. Les endpoints qui renvoient l'enregistrement complet (par exemple les workflows et les exécutions de workflow) incluent aussi ces champs généraux :

created, updated, accessed, permissions et owner_group sont gérés par le serveur. Les valeurs que vous envoyez pour ces champs dans les requêtes de création ou de mise à jour sont ignorées.

Interroger des listes #

Les endpoints qui listent des enregistrements (.../find) et qui les comptent (.../count) prennent le même objet de requête comme corps. L'exemple utilisé tout au long de cette section est POST /api/v3/conversation/find.

Sans sort_key, les enregistrements sont renvoyés du plus récent au plus ancien (par created.timestamp, décroissant). Sans limit_from, tous les enregistrements correspondants sont renvoyés dans une seule réponse.

Pagination #

Pour lire la page n (en comptant à partir de 0) de taille s, envoyez limit_from: n * s et limit_to: (n + 1) * s. Règles :

• limit_from doit valoir 0 ou plus et limit_to doit être supérieur à limit_from. Un limit_from négatif ou un limit_to inférieur à limit_from est rejeté avec 422. Lorsque les deux sont égaux, aucune borne supérieure n'est appliquée et tous les enregistrements à partir de limit_from sont renvoyés.
• limit_to sans limit_from est ignoré : le résultat complet est renvoyé.
• Il n'existe pas de taille de page maximale côté serveur. Gardez des pages raisonnablement petites (jusqu'à quelques centaines d'enregistrements) ; les enregistrements volumineux, comme les conversations avec un long historique, produisent de grosses réponses.

curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["updated.timestamp", ">=", 1790812800000]],
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20
  }'

La réponse est un tableau d'enregistrements ; un tableau vide lorsque rien ne correspond :

[
  {
    "id": "0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90",
    "name": "Quarterly report outline",
    "model": "gpt-5-mini",
    "summary": "",
    "organization_id": null,
    "assistant_id": "c4e2a9b1-7f3d-4e6a-8b5c-1d9f0a2e3b47",
    "task_id": null,
    "task_execution_id": null,
    "workflow_id": null,
    "workflow_run_id": null,
    "messages": [
      {
        "id": "7d3a1f9e-2b4c-4e8a-9f6d-0c5b8e1a2d36",
        "timestamp": 1790846045000,
        "role": "user",
        "content": "Draft an outline for the Q3 report.",
        "reasoning_content": null,
        "model": null,
        "attachments": [],
        "tool_runs": {}
      },
      {
        "id": "e1b9c7a3-5d2f-4a6e-8c0b-9f4d3e2a1b58",
        "timestamp": 1790846052000,
        "role": "assistant",
        "content": "1. Summary\n2. Revenue\n3. Costs\n4. Outlook",
        "reasoning_content": null,
        "model": "gpt-5-mini",
        "attachments": [],
        "tool_runs": {}
      }
    ],
    "public_sharing": false,
    "created": { "timestamp": 1790846045000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" },
    "updated": { "timestamp": 1790846052000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" },
    "accessed": { "timestamp": 1790846052000, "user_id": "5a1d7e3c-9b2f-4c8e-a6d0-3f7b1e9c2a54" }
  }
]

Pour tout lire, demandez des pages jusqu'à ce que l'une d'elles soit plus courte que la taille de page. Triez par created.timestamp croissant, afin que les enregistrements créés pendant la pagination soient ajoutés à la fin au lieu de décaler les pages que vous n'avez pas encore lues :

import os
import requests

BASE = "https://ayeto.ai/api/v3"
HEADERS = {"uni-api-key": os.environ["AYETO_API_KEY"]}
PAGE = 50

start = 0
while True:
    r = requests.post(f"{BASE}/conversation/find", headers=HEADERS, json={
        "sort_key": "created.timestamp",
        "sort_order": 0,
        "limit_from": start,
        "limit_to": start + PAGE,
    })
    r.raise_for_status()
    page = r.json()
    for conversation in page:
        print(conversation["id"], conversation["name"])
    if len(page) < PAGE:
        break
    start += PAGE

Comptage #

Les endpoints .../count prennent le même corps et renvoient le nombre d'enregistrements qui correspondent à filters sous forme d'entier simple. Ils ignorent limit_from, limit_to et les champs de tri, si bien que vous pouvez envoyer le même corps que pour la page affichée et obtenir le total pour la pagination.

curl -X POST "https://ayeto.ai/api/v3/workflow/count" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [["name", "regex", "invoice"]], "limit_from": 0, "limit_to": 20}'

42

Toutes les listes n'ont pas d'endpoint de comptage ; les pages des endpoints indiquent ceux qui existent.

Filtres #

filters est un tableau. Chaque élément est une condition ou un groupe de conditions, et un enregistrement n'est renvoyé que s'il correspond à tous les éléments.

Conditions #

Une condition est un tableau [field, operator, value], avec un quatrième élément facultatif (voir Conversion des UUID) :

["model", "==", "gpt-5-mini"]

field désigne un champ de l'enregistrement. Utilisez la notation pointée pour les champs imbriqués (created.timestamp, created.user_id). Un chemin vers une liste d'objets correspond lorsque n'importe quel élément de la liste correspond (messages.role). id est l'identifiant de l'enregistrement.

Remarques :

• regex est toujours insensible à la casse et non ancrée : "invoice" correspond à "Invoices 2026". Utilisez ^ et $ dans le motif pour l'ancrer, et échappez les caractères d'expression régulière (., *, +, ?, (, ), [, ], \) pour les faire correspondre littéralement.
• Les chaînes sont comparées alphabétiquement (par code de caractère), les nombres numériquement. Comparez les horodatages en tant que nombres.
• ["field", "==", null] correspond aux enregistrements dont le champ vaut null ou est absent.

Groupes #

Un groupe est un objet avec exactement une clé, AND ou OR, dont la valeur est un tableau non vide de conditions ou d'autres groupes. Les groupes peuvent être imbriqués.

{"OR": [["model", "==", "gpt-5-mini"], ["model", "==", "gpt-5"]]}

{"AND": [
  ["updated.timestamp", ">=", 1788220800000],
  {"OR": [["name", "regex", "report"], ["summary", "regex", "report"]]}
]}

La clé doit être écrite en majuscules. Un objet avec toute autre clé (par exemple "or") est ignoré et correspond à tous les enregistrements, si bien qu'une faute de frappe désactive silencieusement cette partie du filtre. Un objet sans clé ou avec plus d'une clé, ainsi qu'un groupe dont la valeur n'est pas un tableau non vide, sont rejetés avec 422. Les groupes peuvent être imbriqués jusqu'à 32 niveaux.

Exemples #

{
  "filters": [
    ["assistant_id", "==", "c4e2a9b1-7f3d-4e6a-8b5c-1d9f0a2e3b47"],
    ["created.timestamp", ">=", 1788220800000],
    ["name", "regex", "^draft"]
  ]
}

{
  "filters": [
    ["id", "in", [
      "0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90",
      "9e7a5c3b-1d2f-4b6a-8e0c-4f3d2a1b9c87"
    ]]
  ]
}

{
  "filters": [
    {"OR": [["organization_id", "==", null], ["organization_id", "==", "2f9c4b7e-8a1d-4e3c-b6f0-5d7a9e2c1b34"]]}
  ]
}

Le serveur vérifie et normalise chaque condition avant d'exécuter la requête. La plupart des résultats vides surprenants proviennent de l'une des règles ci-dessous.

Conversion des UUID #

Une valeur de type chaîne qui est un UUID valide est convertie en UUID avant la comparaison. Les champs qui contiennent des identifiants (id, assistant_id, created.user_id, ...) sont stockés sous forme d'UUID, c'est donc ce que vous voulez pour eux. Un champ qui contient du texte ressemblant par hasard à un UUID (y compris 32 chiffres hexadécimaux sans tirets) ne correspondra plus après la conversion. Ajoutez true comme quatrième élément pour comparer la valeur en tant que texte brut :

["external_ref", "==", "0b8f3c2e5d414a7e9c1f6e2d8a4b7c90", true]

Avec in, le quatrième élément s'applique à chaque valeur de la liste. Les valeurs à l'intérieur d'un tableau utilisé avec == ou != ne sont jamais converties.

Échappement HTML #

Dans les valeurs de type chaîne, <, >, " et ' sont remplacés par <, >, " et ' avant la comparaison. Un filtre portant sur un texte qui contient ces caractères ne correspond donc pas aux enregistrements stockés avec les caractères bruts ; filtrez sur une partie du texte qui ne les contient pas, par exemple avec regex.

Limites des valeurs #

Noms de champs #

Un nom de champ doit commencer par une lettre et ne contenir que des lettres, des chiffres, _ et . (au plus 128 caractères). Les autres noms sont rejetés avec 422.

Les noms de champs dans les filtres ne sont pas vérifiés par rapport à l'enregistrement : un champ mal orthographié ne correspond à rien avec == et à tout avec !=. (sort_key, en revanche, est vérifié.)

Conditions mal formées #

Une condition de moins de trois ou de plus de quatre éléments, ou un élément de filters (ou d'un groupe) qui n'est ni un tableau ni un objet, est rejeté avec 422. detail indique le problème, par exemple A filter condition must be [field, operator, value] with an optional fourth element, got 2 elements.

Erreurs #

Les erreurs utilisent les codes de statut HTTP standard et un corps JSON avec un champ detail :

{"detail": "entity not found, id: 0b8f3c2e-5d41-4a7e-9c1f-6e2d8a4b7c90"}

detail est un message lisible en anglais. Ne l'analysez pas, sauf lorsqu'une page d'endpoint documente un message précis.

Lorsque la requête elle-même ne correspond pas au schéma de l'endpoint (un champ manquant ou de mauvais type, un UUID invalide, un en-tête manquant, pas de corps), le statut est 422 et detail est une liste qui pointe vers chaque problème :

{
  "detail": [
    {
      "loc": ["body", "sort_order"],
      "msg": "value is not a valid enumeration member; permitted: 0, 1",
      "type": "type_error.enum",
      "ctx": {"enum_values": [0, 1]}
    }
  ]
}

loc est l'emplacement du problème : body, query ou header, suivi du chemin du champ.

Une réponse diffère de cette forme : une défaillance inattendue du serveur peut renvoyer 500 avec le corps en texte brut Internal Server Error.

Lisez d'abord le code de statut et considérez le corps comme une information facultative.

L'API n'utilise pas 402 ; les erreurs de crédits sont des 422, comme décrit ci-dessus. Un en-tête uni-api-key absent (par opposition à une valeur vide ou erronée) est une erreur de schéma et renvoie 422, pas 401.

Les réponses aux vérifications de clé API échouées (401) et aux requêtes soumises à la limite de débit (429) sont volontairement retardées d'environ une seconde, pour ralentir les tentatives de deviner une clé. Tenez-en compte dans vos délais d'expiration et ne considérez pas ce délai comme un problème du serveur.

Les erreurs qui surviennent après le début d'un stream sont signalées à l'intérieur du stream, et non par un statut HTTP.

Limites de débit #

Les requêtes sont soumises à une limite de débit par adresse IP du client et par endpoint : chaque chemin d'endpoint a ses propres compteurs, et toutes les requêtes d'une même adresse IP vers cet endpoint sont comptées ensemble, quelle que soit la clé API utilisée. Les requêtes sont comptées même lorsqu'elles échouent, y compris les requêtes rejetées pour une mauvaise clé API.

Chaque endpoint a trois limites vérifiées en même temps : par minute, par heure et par jour. Ce sont des fenêtres glissantes : une requête compte dans une fenêtre pendant toute la durée de cette fenêtre après avoir été effectuée, si bien que la capacité se libère progressivement plutôt qu'au début de chaque minute ou heure. Chaque page d'endpoint indique son niveau :

Le niveau webhook s'applique uniquement au webhook de workflow public, qui limite en plus chaque déclencheur séparément. Le niveau static est une protection contre l'afflux de requêtes pour les endpoints interrogés souvent, comme la version du serveur.

Lorsqu'une limite est dépassée, l'API renvoie 429 avec un en-tête Retry-After : le nombre de secondes entières avant que la fenêtre n'ait de la place pour une nouvelle requête.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{"detail": "Too many requests"}

Les réponses réussies ne portent aucun en-tête de limite de débit ; suivez donc vous-même votre débit de requêtes. Pour rester dans les limites :

• Attendez au moins Retry-After secondes avant de réessayer ; ne réessayez jamais un 429 dans une boucle serrée.
• En cas d'échecs répétés (429, 5xx), utilisez un backoff exponentiel avec une part d'aléa (jitter).
• Étalez les traitements par lots dans le temps au lieu de les envoyer en rafales, et mettez en cache les listes que vous lisez souvent au lieu de les récupérer à chaque utilisation.
• Plusieurs workers derrière une même adresse IP partagent les limites ; prévoyez un budget pour l'ensemble.

Streaming #

Le chat et certains endpoints de workflow peuvent transmettre leur sortie en streaming : la réponse est envoyée en chunks pendant sa génération, au lieu d'un seul corps JSON à la fin. Le format des chunks, le signal de fin de stream et la façon dont les erreurs sont signalées en cours de stream sont décrits dans Streaming.