API publique

Une API REST versionnée pour votre propre code : conversations avec un agent, pièces jointes, retours, recherche dans les connaissances et pipelines de texte, authentifiée par des clés d'API de projet.

L'API publique vit sous /api/v1 et n'accepte que des clés d'API. Une session de navigateur n'y est jamais acceptée, et une clé n'est jamais acceptée sur les points d'accès propres au Studio, sous /api/internal. Les deux surfaces sont tenues séparées à dessein, et la surface publique est plus étroite : construire des agents, publier des versions et gérer les membres se font dans le Studio.

Ce qu'elle expose

Domaine	Routes	Portée
Conversations	POST /api/v1/agents/{agentId}/conversations envoie un message, dans une nouvelle conversation ou dans celle que désigne conversationId. GET sur le même chemin liste les conversations de l'agent, GET …/conversations/{conversationId} renvoie un fil.	full pour envoyer, read pour lister
Diffusion en continu	GET …/conversations/{conversationId}/runs/{runId}/stream, en Server-Sent Events	read
Pièces jointes	POST …/conversations/attachments (multipart) dépose un fichier qu'un message cite ensuite dans attachmentIds. GET …/conversations/attachments/{attachmentId}/download renvoie une URL de téléchargement de courte durée.	full / read
Retours	POST …/conversations/{conversationId}/feedback, une note de 1 ou -1 et un commentaire facultatif	full
Recherche dans les connaissances	POST /api/v1/knowledge/search lance une recherche dans des collections, GET /api/v1/knowledge/search/{searchId} en renvoie les résultats	read
Pipelines	POST /api/v1/pipelines/execute exécute summarize, classify, translate ou extract_entities sur un texte. GET /api/v1/pipelines/results liste les résultats.	full / read
Bac à sable	GET /api/v1/sandbox/requirement lit la politique de bac à sable de l'instance, POST /api/v1/sandbox/validate-mcp vérifie l'exécution MCP dans un bac à sable	read / full

{agentId} est l'UUID de l'agent. La carte API headless de l'onglet Deploy de l'agent affiche le point d'accès complet.

Clés

• Une clé appartient à un projet et porte une portée : read, ou full, qui couvre aussi les routes read.
• Son préfixe fixe l'environnement, rk_live_ ou rk_test_, et l'agent a besoin d'un déploiement d'API actif dans ce même environnement. Couper l'interrupteur API de l'onglet Deploy coupe le trafic /api/v1 de l'agent, lecture comprise.
• Elle peut être restreinte à des agents précis, pour qu'une intégration n'atteigne que ce dont elle a besoin.
• Elle peut porter une date d'expiration.
• Sa valeur complète est affichée une fois, à la création. Rikoo n'en conserve qu'une empreinte SHA-256.
• La révocation d'une clé prend effet à la requête suivante.

Envoyez-la dans l'en-tête Authorization, avec ou sans le préfixe Bearer.

curl -X POST "https://rikoo.example.com/api/v1/agents/$AGENT_ID/conversations" \
  -H "Authorization: Bearer $RIKOO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-question-0001" \
  -d '{"message":"My invoice is wrong","sync":true}'

Avec "sync": true, l'appel attend la fin de l'exécution et renvoie la réponse. Sans cette option, l'appel renvoie aussitôt le conversationId et le runId, et vous suivez l'exécution sur son flux. L'en-tête Idempotency-Key est facultatif : une nouvelle tentative sous la même clé obtient la même réponse au lieu de créer un second tour.

Diffusion en continu

Le flux d'une exécution est un flux Server-Sent Events de ses événements : la réponse à mesure que le modèle la produit (message.delta), les appels d'outils au moment où ils se font, et un événement terminal (run.completed, run.failed, run.aborted ou run.refused) qui le ferme. Il commence par rejouer ce que l'exécution a déjà enregistré : un client qui se connecte tard ou se reconnecte ne perd rien, et les longues conversations n'ont pas besoin d'une boucle d'interrogation.

Le contrat est généré depuis le code

L'instance sert sa description OpenAPI sous /api/openapi.json, avec une vue interactive sous /api/docs. Elle est générée depuis le code qui sert les routes, pas écrite à la main. Les routes sous /api/v1 forment le contrat public.