Référence de l'API Jenova Agent

URL de base : https://api.jenova.ai/v1

Authentification : Token Bearer dans l'en-tête Authorization

Table des matières

• Présentation
• Démarrage rapide
• Concepts fondamentaux
• Authentification
• Points de terminaison de l'API
  • Messages
  • Sessions
  • Opérations
  • Crédits
  • Agents
  • Modèles
  • Documentation
• Diffusion en continu (SSE)
• Intégration du serveur MCP
• Facturation
• Limites de débit
• Gestion des erreurs
• Pagination
• Localisation
• Confidentialité et données
• Support

Présentation

Créez et exécutez des agents IA prêts pour la production sans avoir à assembler vous-même la pile technologique sous-jacente. L'API Jenova Agent réunit toutes les capacités essentielles au sein d'un service géré unique :

La pile Agent complète

• Orchestration d'Agent : Une couche d'orchestration unifiée coordonne modèles, outils, mémoire et récupération à travers des workflows complexes.
• Mémoire et contexte : Mémoire de conversation et contexte illimités intégrés à chaque Session. Aucune gestion d'état externe requise.
• Outils et MCP : Intégrations d'Outils illimitées avec des outils natifs de la plateforme et n'importe quel serveur MCP distant, prêtes à l'emploi.
• Utilisez n'importe quel Modèle : Alimentez vos Agents avec des Modèles d'OpenAI, Anthropic, Google, xAI, Qwen, et bien d'autres, via une intégration unique.
• Stockage entièrement géré : Bases de données relationnelles et vectorielles gérées avec RAG intégré. Aucune infrastructure à provisionner ou à faire évoluer.
• Niveau production : Utilisé par des centaines de milliers d'utilisateurs. Infrastructure entièrement gérée, API stables, conçu pour le trafic de production.

Démarrage rapide

1. Obtenez votre clé API

Générez une Clé API depuis le Tableau de bord développeur à l'adresse www.jenova.ai/platform. Les clés utilisent le format jnv_sk_* et sont transmises sous forme de Tokens Bearer.

2. Choisissez ou créez un Agent

Choisissez un Agent prédéfini sur la plateforme, ou créez un Agent personnalisé dans le Tableau de bord avec des instructions, des paramètres de Modèle, des fichiers de Base de connaissances, des Outils et des serveurs MCP.

3. Envoyez votre premier Message

Créez une Session et envoyez un message en un seul appel :

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

La réponse est renvoyée en continu sous forme de Server-Sent Events :

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Récupérez session_id depuis stream_started pour les requêtes de suivi. Pour les réponses JSON synchrones, consultez Envoyer un Message.

Concepts fondamentaux

Agent

Un agent IA avec lequel vous interagissez via l'API. Chaque Agent possède un slug unique (par exemple, my-support-agent) utilisé comme valeur agent dans les appels API.

• Prédéfini : Sélectionnez parmi les Agents existants sur la plateforme.
• Personnalisé : Configurez le vôtre dans le Tableau de bord avec des instructions, un Modèle, une Base de connaissances, des Outils et des serveurs MCP.

Session

Un fil de conversation indépendant entre un Utilisateur final et un Agent.

• Identifiant : ID préfixé (par exemple, ses_abc123)
• Portée : Plusieurs Sessions peuvent exister pour le même Agent et le même Utilisateur final, chacune avec un état de conversation indépendant
• Cycle de vie : Les Sessions persistent indéfiniment jusqu'à leur suppression via l'API. Pour les tâches ponctuelles sans stockage, utilisez POST /messages avec ephemeral: true
• Isolation entre plateformes : Les Sessions de l'API sont distinctes des conversations dans l'application web Jenova. Les Utilisateurs finaux, l'historique des Sessions et la Facturation sont indépendants entre l'API et l'application web.

Message

Une entrée unique dans l'historique de conversation d'une Session, renvoyée par les points de terminaison Messages. Chaque Message inclut un objet from structuré avec type ("user" ou "agent") et name, ainsi qu'un type de message :

• external - un message de conversation destiné à être affiché comme contenu de chat.
• internal - un message facultatif représentant les étapes de travail de l'Agent pendant une Exécution, comme des appels d'Outils ou de la récupération.

Exécution

Une exécution unique de l'Agent créée lors de l'envoi d'un Message. Une Exécution possède un run_id, peut diffuser des Événements en continu pendant qu'elle est active, et produit un ou plusieurs Messages achevés. Chaque Session ne peut avoir qu'une seule Exécution active à la fois.

Utilisateur final

Le champ user associe les Sessions à un Utilisateur final dans votre application. Utilisez un ID opaque stable, tel que votre ID d'utilisateur interne ou un UUID. Évitez les adresses e-mail ou autres données personnelles sauf si votre application les exige. Les Sessions créées avec la même valeur user sont regroupées, ce qui permet le listage des Sessions par Utilisateur final.

Si user est omis, la Session est associée à votre compte développeur et ne pourra pas être filtrée ultérieurement par Utilisateur final. Transmettez user en production.

Pour les requêtes portant sur une Session existante, user est une protection de propriété facultative. Si vous le fournissez, il doit correspondre à la valeur user utilisée lors de la création de la Session ; dans le cas contraire, l'API renvoie 404 session_not_owned. Transmettez-le en paramètre de requête pour les requêtes GET et DELETE, et dans le corps JSON pour les requêtes POST et PATCH.

Authentification

Authentifiez chaque requête avec un Token Bearer dans l'en-tête Authorization :

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les clés API sont générées à partir du tableau de bord développeur.

User-Agent est facultatif. Les SDK peuvent le définir à des fins de diagnostic, mais l'API ne l'exige pas.

Format de clé : Les clés commencent par le préfixe jnv_sk_ suivi d'une chaîne aléatoire encodée en base62.

Limites : Chaque compte développeur peut avoir jusqu'à 10 clés API actives.

Points de terminaison de l'API

Messages

L'envoi de Messages constitue le chemin principal de l'API. Utilisez POST /messages pour le premier message ; cela crée la session et démarre l'exécution en une seule requête. Utilisez POST /sessions/{session_id}/messages pour continuer une session_id déjà capturée.

Envoyer un Message

POST /messages

Crée une session persistante et envoie le premier message en une seule requête atomique. Définissez ephemeral: true pour une requête ponctuelle en diffusion continue sans stockage, qui ne stocke aucun historique de session ni de messages, ne renvoie aucun ID de session, et ne peut pas être poursuivie.

Corps de la requête

Exemple - Diffusion en continu (par défaut)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

La réponse est un flux SSE (voir Diffusion en continu (SSE) pour le format des événements). Les requêtes persistantes incluent le nouveau session_id ; les requêtes avec ephemeral: true omettent session_id et doivent utiliser la diffusion en continu.

Exemple - JSON (sans diffusion en continu)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Réponse

Les réponses en diffusion continue émettent les événements SSE décrits dans Diffusion en continu (SSE). Les réponses sans diffusion en continu renvoient la structure JSON de message présentée dans Continuer la Session, incluant stop_reason et usage pour la requête terminée.

Si une exécution sans diffusion en continu est toujours en cours de traitement après 90 secondes, l'API renvoie 202 Accepted avec status: "processing", session_id, run_id, et message. L'exécution se poursuit après la réponse ou la déconnexion du client ; consultez les messages de la session, ou utilisez la diffusion en continu pour les workflows plus longs.

Erreurs

Continuer la Session

POST /sessions/{session_id}/messages

Envoie un message à une Session persistante existante et reçoit la réponse de l'agent. Les réponses sont diffusées en continu via SSE par défaut ; définissez stream: false pour obtenir du JSON.

Corps de la requête

Exemple - Diffusion en continu (par défaut)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Exemple - JSON (sans diffusion en continu)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Réponse 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Si la Session possède déjà une exécution active ou des messages en attente, l'API renvoie un JSON 202 Accepted avec status: "queued", session_id, run_id et message_id. Le Message de l'utilisateur est traité par l'exécution active.

Erreurs

Idempotence

POST /messages et POST /sessions/{session_id}/messages acceptent un en-tête facultatif Idempotency-Key. Utilisez une clé unique pour chaque envoi logique de l'utilisateur afin que les nouvelles tentatives réseau ou les doubles soumissions ne créent pas d'exécutions dupliquées.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Sans diffusion en continu : Une nouvelle tentative renvoie la réponse 200 ou 202 enregistrée avec l'en-tête Idempotent-Replayed: true.

Diffusion en continu : Le flux n'est pas rejoué. Une nouvelle tentative pendant l'exécution ou après son achèvement renvoie une erreur d'idempotence avec le run_id d'origine et, pour les requêtes persistantes, le session_id. Utilisez GET /sessions/{session_id}/runs/{run_id} pour vérifier une exécution active, ou GET /sessions/{session_id}/messages pour récupérer les résultats persistés.

Exemple de nouvelle tentative sur une diffusion en continu terminée :

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Erreurs d'idempotence

Lister les Messages

GET /sessions/{session_id}/messages

Retourne une liste paginée des messages de conversation visibles. La première page contient les messages les plus récents ; au sein de chaque page, les messages sont classés par ordre chronologique (du plus ancien au plus récent). sequence est un numéro d'ordre stable au sein de la session.

Paramètres de requête

Exemple

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Réponse 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "files": []
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Objet Message

Objet Fichier

Erreurs

Obtenir un Message

GET /sessions/{session_id}/messages/{message_id}

Récupère un message visible unique par son ID.

Réponse 200 OK

Retourne un objet message unique avec la même structure que la réponse de liste.

Erreurs

Pièces jointes

Fournissez des URL HTTPS accessibles publiquement dans le champ file_urls.

Formats pris en charge

• Images : JPG, JPEG, PNG, WebP
• Documents : PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Code : JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

Lors du listage des messages, les fichiers joints apparaissent dans le tableau files du message.

Sessions

Les sessions sont des conversations persistantes entre un utilisateur final et un agent. La plupart des intégrations peuvent les créer implicitement avec POST /messages.

Créer une Session

POST /sessions

Crée une session persistante vide liée à un agent spécifique. Utilisez cette opération lorsque vous avez besoin d'un identifiant de session avant le premier message ; sinon, privilégiez POST /messages.

Remarque : ephemeral n'est pas accepté sur POST /sessions ; utilisez POST /messages avec ephemeral: true pour les requêtes ponctuelles sans stockage.

Corps de la requête

Exemple

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Réponse 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Erreurs

Lister les Sessions

GET /sessions

Retourne une liste paginée de vos sessions, triées par date de mise à jour la plus récente.

Paramètres de requête

Exemple

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Réponse 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAxIn0",
  "has_more": true
}

Erreurs

Obtenir une Session

GET /sessions/{session_id}

Récupère une session unique par son identifiant.

Réponse 200 OK

Retourne un objet session ayant la même structure que la réponse de création.

Erreurs

Renommer la Session

PATCH /sessions/{session_id}

Met à jour le nom d'affichage d'une session.

Corps de la requête

Réponse 200 OK

Retourne l'objet session mis à jour.

Erreurs

Supprimer la Session

DELETE /sessions/{session_id}

Supprime définitivement une session et tous ses messages. La session ne doit pas avoir d'exécution active.

Réponse 204 No Content

Erreurs

Opérations

Ces points de terminaison sont des contrôles de récupération et d'édition pour les sessions persistantes. La plupart des intégrations n'ont besoin que d'Annuler ; utilisez les autres opérations lorsque vous souhaitez intentionnellement modifier ou récupérer l'état d'une session. Toutes les opérations prennent en charge le mécanisme de contrôle de propriété facultatif user décrit dans Utilisateur final.

Annuler l'Exécution active

POST /sessions/{session_id}/cancel

Annule l'exécution d'agent en cours. Cela ne supprime pas les messages déjà terminés avant l'annulation.

Corps de la requête

Réponse 204 No Content

Erreurs

Défaire l'Exécution active

POST /sessions/{session_id}/undo

Annule l'exécution active, attend son arrêt, puis supprime tous les messages qu'elle avait déjà ajoutés. Aucune sortie supplémentaire n'est conservée après l'émission de la commande « Défaire ».

Corps de la requête

Réponse 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Si l'exécution est annulée avant qu'aucun message ne soit terminé, deleted est un tableau vide.

Erreurs

Supprimer les Messages récents

POST /sessions/{session_id}/messages/delete

Supprime les N Messages les plus récents d'une Session inactive. La Session ne doit pas avoir d'Exécution active.

Corps de la requête

Réponse 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Erreurs

Dupliquer la Session (Fork)

POST /sessions/{session_id}/fork

Crée une nouvelle Session en copiant la Session source jusqu'à un Message spécifique. La Session source ne doit pas avoir d'Exécution active.

Corps de la requête

Réponse 201 Created

Retourne l'objet de la Session nouvellement créée, avec la même structure que celle utilisée lors de la création d'une Session.

Erreurs

Obtenir l'état de l'Exécution

GET /sessions/{session_id}/runs/{run_id}

Retourne l'état actuel d'une Exécution active. Utilisez cette opération après une connexion SSE interrompue ou une réponse d'idempotence ayant renvoyé un run_id. Une fois l'Exécution terminée, récupérez les résultats via GET /sessions/{session_id}/messages.

Réponse 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

La réponse peut également inclure des indications de progression récentes tant que l'Exécution est active.

Erreurs

Crédits

Obtenir le solde

GET /credits/balance

Retourne votre solde de Crédits actuel.

Réponse 200 OK

{
  "balance": "123.45"
}

Agents

Créez et modifiez des Agents personnalisés dans le Tableau de bord. La prise en charge de la création et de la modification d'Agents via l'API arrive prochainement.

Les flux de travail planifiés/en arrière-plan ne sont actuellement pas pris en charge via l'API. Le Support arrive prochainement.

Lister les Agents

GET /agents

Retourne les agents disponibles pour votre Clé API. Utilisez la valeur agent lors de la création de sessions ou de l'envoi de messages.

Réponse 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Modèles

Lister les Modèles

GET /models

Retourne tous les modèles disponibles pour une utilisation dans le champ model lors de l'envoi de messages.

Réponse 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "kimi-k2.6",
      "name": "Kimi K2.6",
      "thinking_variant": "kimi-k2.6-thinking"
    }
  ]
}

Les modèles disposant d'un thinking_variant prennent en charge le raisonnement étendu. Utilisez directement l'ID de la variante dans le champ model pour l'activer.

Si aucun model n'est spécifié lors de l'envoi d'un message, le modèle par défaut de l'agent est utilisé.

Documentation

GET /docs?lang=en
GET /doc?lang=en

Retourne cette référence au format Markdown. Utilisez lang pour sélectionner la langue.

Diffusion en continu (SSE)

Lorsque stream est omis ou vaut true (valeur par défaut), les réponses aux messages sont livrées sous forme de Server-Sent Events. Utilisez les Événements message_completed pour identifier les messages prêts à être récupérés ou affichés.

Délai d'expiration : les connexions SSE restent ouvertes pendant 60 minutes maximum. Les requêtes non diffusées en continu attendent jusqu'à 90 secondes, puis retournent 202 Accepted tandis que l'exécution se poursuit.

En-têtes de connexion

La réponse SSE définit les en-têtes suivants :

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id est disponible avant le premier Événement SSE.

Reconnexion et récupération

Les flux SSE ne sont pas rejoués. Si la connexion est interrompue, utilisez le session_id et le run_id capturés pour récupérer l'état :

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Si l'exécution est toujours active, cela retourne le statut actuel, le texte partiel et la progression récente. Si la réponse est 404 not_found, l'exécution n'est plus active ; récupérez les messages de la session pour reconstituer la sortie terminée :

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Format des trames

Chaque trame SSE suit le format standard :

event: <event_type>
data: <json_payload>

Deux retours à la ligne terminent chaque trame.

Types d'Événements

Les flux incluent des événements de cycle de vie, delta de texte, réflexion, progression, avertissement, achèvement de message, connexion MCP, erreur, final et ping. Certains types d’événements ne sont envoyés que lorsqu’ils sont pertinents.

Pour les requêtes éphémères (ephemeral: true), chaque Événement SSE omet session_id. Utilisez uniquement run_id pour corréler les Événements à l'intérieur de ce flux unique.

Pour la réconciliation finale sur les requêtes persistantes, attendez l'Événement stream_ended, puis appelez List Messages.

Champs communs des Événements liés à une Exécution :

stream_started

Envoyé une fois au démarrage de l'Exécution.

stream_delta

Envoyé de manière répétée au fur et à mesure que l'Agent génère le texte de réponse visible. Concaténez les valeurs de chunk_content dans l'ordre de seq pour reconstituer la réponse diffusée en continu.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Envoyé de manière répétée pendant que l'Agent émet une sortie de réflexion. Utilisez cet Événement pour un indicateur de réflexion distinct ou une vue de trace ; ne le concaténez pas dans le texte de réponse final.

stream_progress

Signale une activité visible par l’utilisateur pendant la génération, par exemple la lecture d’un document, la recherche sur le web ou l’attente d’une action utilisateur. Ces événements sont destinés à un affichage temporaire dans l’interface ; ignorez les champs inconnus. Utilisez les messages terminés comme historique de messages faisant autorité.

Avancé : les requêtes de Message acceptent include_progress: false pour omettre uniquement stream_progress. Les Événements de cycle de vie, ping, message_completed, les erreurs et les Événements terminaux sont toujours envoyés lorsque cela est pertinent.

Certains Événements de progression peuvent inclure url, file_name ou server_name comme indices d'affichage facultatifs.

message_completed

Envoyé chaque fois qu'un Message est complet et prêt à être récupéré ou affiché.

Ceci est un marqueur de délimitation, pas l'objet Message complet. Récupérez le Message si vous avez besoin de son contenu ou de ses métadonnées.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"Jenova"},"type":"external"}

mcp_connection

Envoyé lorsque l’agent a besoin que l’utilisateur final connecte ou autorise un ou plusieurs serveurs MCP avant de pouvoir continuer. Cet événement est uniquement disponible en mode streaming.

mcp_connection_resolved

Envoyé lorsque l’action utilisateur de connexion MCP a été résolue ou a expiré.

Aucun champ supplémentaire en dehors des champs communs liés à l'Exécution.

warning

Envoyé pour des avertissements non fatals survenus pendant une Exécution.

stream_error

Envoyé lorsqu'une Exécution échoue. Un Événement final stream_ended peut suivre avec success:false et stop_reason:"error".

stream_ended

Envoyé une seule fois lorsque l'exécution se termine. Il s'agit de l'événement final du flux.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Exemple d'échec :

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Trames de maintien de connexion envoyées toutes les 15 secondes pour éviter les délais d'expiration des proxys/CDN. Ignorez-les dans votre client.

Intégration du serveur MCP

Connectez vos Agents à des Outils externes via le Model Context Protocol (MCP) :

• Serveurs MCP gérés par Jenova : serveurs hébergés par Jenova pour la recherche, la récupération de contenu, la génération de documents et d'autres fonctionnalités intégrées
• Serveurs MCP distants : autres serveurs MCP distants configurés pour votre Agent

Les serveurs MCP doivent être configurés dans le tableau de bord lors de la création ou de la modification de votre Agent. Pour utiliser votre propre serveur MCP, ajoutez-le à un Agent personnalisé, puis appelez cet Agent via l'API. L'API exécute les Outils activés dans la configuration de l'Agent ; aucune configuration supplémentaire n'est requise dans les requêtes API.

Lorsqu'un Agent utilise des Outils MCP au cours d'une réponse, des Événements de progression sont envoyés dans le flux à mesure qu'ils se produisent :

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Si l’agent a besoin que l’utilisateur final se connecte à un serveur MCP ou l’autorise pendant l’exécution, les réponses en streaming peuvent inclure les événements mcp_connection et mcp_connection_resolved. Présentez la liste des serveurs à connecter à votre utilisateur final et ouvrez l’auth_url fournie lorsqu’elle est présente. Gardez le flux SSE ouvert pendant que l’utilisateur connecte ou autorise le serveur.

Après l'autorisation, Jenova stocke le Token, la fenêtre d'autorisation affiche une page de confirmation, et la même Exécution se poursuit automatiquement. L'Utilisateur final n'a pas besoin de renvoyer le Message.

Si l’utilisateur final ne se connecte pas, n’autorise pas, n’ignore pas ou ne met pas en sourdine avant user_action_deadline_unix, l’exécution se termine avec stop_reason:"user_action_timeout". Vous pouvez également annuler l’exécution active avec POST /sessions/{session_id}/cancel.

Stockez l’auth_url côté client. Si le client se déconnecte pendant l’autorisation, l’URL reste valide jusqu’à user_action_deadline_unix. Pour les requêtes persistantes, reconnectez-vous via Get Run Status, ou récupérez les messages une fois l’exécution terminée.

Les requêtes non streaming (stream: false) ne prennent pas en charge les actions utilisateur de connexion MCP ; utilisez le streaming pour les agents qui peuvent nécessiter cette interaction.

Ignorer la connexion MCP

POST /sessions/{session_id}/mcp/connection/skip

Ignore une action utilisateur de connexion MCP en attente et permet à l’exécution de continuer sans cette connexion.

Pour mettre en sourdine les futures demandes de connexion pour un serveur pour le même utilisateur de l’API, incluez mcp_server_id et mute. Les valeurs prises en charge sont 24h et forever.

Corps de la requête

Réponse 204 No Content

Le flux émet mcp_connection_resolved, puis l’exécution se poursuit avec le même run_id.

Erreurs

Facturation

Tous les Coûts sont déduits de votre solde de Crédits développeur. Consultez l'Utilisation et rechargez des Crédits sur www.jenova.ai/platform.

Tarification

Le Coût d'un Message dépend :

• du Modèle - les Coûts par token varient selon les Modèles
• de la longueur du contexte - les Sessions plus longues consomment davantage de tokens d'entrée par requête
• de la complexité du workflow - des workflows plus longs et une utilisation plus intensive des Outils (recherche web, génération de fichiers, analyse de documents) augmentent la consommation totale de tokens

Le Coût réel est renvoyé dans stream_ended.usage.cost pour les requêtes en Diffusion en continu et dans usage.cost pour les requêtes JSON non-Diffusion en continu.

Retenues de crédits

Chaque nouvelle Exécution de Message place une retenue de 0,50 $ sur votre solde de Crédits avant le début de l'exécution. Cela réserve des fonds pour l'Exécution. Les Messages de suivi mis en file d'attente dans une Exécution active ne créent pas de retenues supplémentaires ; l'Utilisation de l'Exécution active est vérifiée par rapport à votre solde restant.

Lorsque l'Exécution se termine, la retenue est ajustée au Coût réel et la différence est libérée. Les Exécutions annulées et échouées ne sont facturées que pour l'Utilisation déjà engagée. Si une requête échoue avant d'atteindre le Modèle, la retenue complète est libérée.

Cela signifie que votre solde disponible peut temporairement paraître inférieur pendant les requêtes en cours. Vous devez disposer d'au moins 0,50 $ de solde disponible pour envoyer un Message à une Session existante ou pour envoyer un Message éphémère. Une première requête POST /messages persistante crée une Session et nécessite au moins 0,51 $ pour couvrir la retenue du Message ainsi que les frais de création de Session.

Limites de débit

Chaque compte développeur est soumis à trois dimensions de limite de débit :

Les requêtes GET et HEAD ne consomment pas d’emplacements concurrents. cancel, undo et mcp/connection/skip ne consomment pas non plus d’emplacements concurrents ; ces opérations restent donc disponibles lorsque tous les emplacements sont utilisés. Ces requêtes comptent toujours dans le RPM et le RPD.

En-têtes de réponse

Les réponses de l'API authentifiées incluent des en-têtes de limite de débit :

Lorsqu'une limite est dépassée, l'API retourne 429 Too Many Requests :

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}

Gestion des erreurs

Les erreurs HTTP immédiates et les erreurs d'exécution non diffusées en continu suivent une enveloppe cohérente :

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

Les messages d'erreur sont localisés en fonction du paramètre lang (voir Localisation).

Les erreurs d'exécution en diffusion continue sont transmises sous forme d'Événements stream_error. Une Exécution ayant échoué peut néanmoins envoyer un Événement final stream_ended avec success:false et stop_reason défini. Les erreurs d'exécution non diffusées en continu peuvent également inclure un objet usage de premier niveau lorsque les données de coût sont disponibles.

Les erreurs spécifiques à chaque point de terminaison sont documentées directement sous chaque point de terminaison.

Erreurs d'Exécution après le démarrage

Les erreurs d'Exécution apparaissent après le démarrage d'une exécution de message. En mode diffusion en continu, elles apparaissent sous forme d'Événements stream_error et peuvent être suivies d'un stream_ended avec success:false. En mode non diffusé en continu, elles sont renvoyées sous forme de réponse d'erreur JSON avec le code d'état HTTP ci-dessous.

Pagination

Les points de terminaison de liste utilisent une pagination basée sur un curseur :

{
  "items": [],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAyIn0",
  "has_more": true
}

Transmettez next_cursor en tant que paramètre de requête cursor pour récupérer la page suivante. Lorsque has_more vaut false, il n'y a plus de résultats.

Localisation

Tous les points de terminaison acceptent un paramètre de requête facultatif lang permettant de contrôler la langue des messages d'erreur et de tout contenu localisé.

Vous pouvez ajouter ?lang=xx à n'importe quelle URL de requête :

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Langues prises en charge : en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Confidentialité et données

Jenova n'utilise pas les invites, les résultats, l'historique des conversations, les fichiers téléversés, les instructions d'Agent ni les Bases de connaissances issus de l'API pour entraîner les Modèles Jenova.

Pour les fournisseurs de modèles tiers, Jenova utilise des canaux d'API commerciaux, des paramètres de compte, des engagements contractuels ou des mécanismes de retrait destinés à empêcher que le contenu des clients soit utilisé pour entraîner les modèles des fournisseurs.

Jenova stocke et traite les données de l'API à l'aide d'une infrastructure basée aux États-Unis. Les fournisseurs tiers peuvent traiter les données dans d'autres juridictions, comme décrit dans la Politique de confidentialité et les Conditions d'utilisation.

Pour plus de détails, consultez les Conditions d'utilisation, la Politique de confidentialité et la Politique d'utilisation.

Support

• Tableau de bord : www.jenova.ai/platform
• E-mail : [email protected]