En bref
- Agents, chats et contacts.Créez, lisez, modifiez et supprimez des agents, et lisez conversations, messages et contacts.
- Des clés avec seulement ce qu'il leur faut.Des clés secrètes pour vos serveurs, des clés restreintes limitées aux permissions que vous cochez.
- OpenAPI 3.1 inclus.Une description lisible par machine est servie en direct, générée à partir des mêmes règles que celles que vérifie l'API.
- Sans risque de relance.Envoyez une Idempotency-Key et une écriture retentée renvoie le premier résultat au lieu de s'exécuter deux fois.
Une API permet à votre propre logiciel de parler directement à OneType. Les agences configurent des agents pour leurs clients depuis un script, les équipes produit importent les conversations dans leurs propres rapports, et les équipes d'exploitation gardent les réglages des agents dans le code. L'API REST vous donne les mêmes données et les mêmes règles que le tableau de bord, en HTTPS simple.
Ce que vous pouvez faire
- Agents : lister, créer, lire, modifier et supprimer, y compris instructions, modèle, domaines autorisés et questions suggérées.
- Conversations : les lister par agent, statut ou date de début, en lire une, et lire ses messages.
- Contacts : lister et lire les personnes que votre agent a rencontrées.
- Chat : ouvrir une conversation et obtenir la réponse de l'agent, en JSON ou en flux.
- Téléchargez la description OpenAPI 3.1 sur /v1/openapi.json.
Chaque message indique s'il a été écrit par une IA ou par votre équipe. Les listes utilisent des curseurs, de 1 à 100 éléments par page, et restent stables pendant que de nouveaux éléments arrivent. Une modification peut porter la révision que vous avez lue, afin qu'un changement fait entre-temps par quelqu'un soit refusé au lieu d'être écrasé.
Clés API avec périmètre
Les propriétaires et les admins créent des clés dans « Developer », « API keys ». Une clé secrète peut faire ce que peut faire un admin de l'espace de travail, sauf gérer les clés et les actions réservées aux propriétaires. Une clé restreinte ne détient que les permissions que vous cochez, jamais plus que les vôtres. Utilisez une clé restreinte par intégration ou par script, pour que chacune ne puisse faire que sa tâche.
Une clé n'est affichée qu'une fois et stockée sous forme de hachage. La liste montre les derniers caractères de chaque clé et sa dernière utilisation. Révoquez une clé et la requête suivante qui l'utilise échoue. Les clés appartiennent à un seul espace de travail et ne peuvent jamais lire les données d'un autre.
Conçu pour de vraies intégrations
Chaque erreur a la même forme, avec un code stable, un message, des détails de champ quand ils s'appliquent et un identifiant de requête. Envoyez Idempotency-Key lors d'une écriture et le premier résultat est conservé 24 heures, donc une nouvelle tentative après un dépassement de délai ne crée jamais un second agent ni une seconde réponse.
Chaque clé peut faire 100 requêtes et jusqu'à 20 messages de chat toutes les 10 secondes. Les en-têtes RateLimit indiquent ce qu'il reste, et une réponse 429 dit combien de temps attendre. Les limites sont les mêmes avec toutes les offres payantes. Les requêtes avec une mauvaise clé sont limitées par adresse réseau.
Ce que l'API ne couvre pas encore
Les sources de connaissances, l'usage, les webhooks et les intégrations se gèrent dans le tableau de bord, pas par l'API. Les contacts sont en lecture seule. Les clés sont réservées aux serveurs : il n'existe pas encore de clé pour navigateur. Aucun SDK n'est publié sur npm aujourd'hui, utilisez donc du HTTPS simple ou générez un client à partir du fichier OpenAPI.
Le fichier OpenAPI est généré à partir des mêmes schémas que ceux utilisés par l'API pour vérifier les requêtes, il ne s'écarte donc jamais de ce que le serveur accepte. L'API ne change qu'en ajoutant des choses : de nouveaux champs, de nouveaux endpoints et de nouveaux types d'événements, si bien que le code qui ignore les champs inconnus continue de fonctionner.