Riferimento API Agente Jenova

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

Autenticazione: Bearer token nell'header Authorization

Indice

• Panoramica
• Guida introduttiva
• Concetti fondamentali
• Autenticazione
• Endpoint API
  • Messaggi
  • Sessioni
  • Operazioni
  • Crediti
  • Agenti
  • Modelli
  • Documentazione
• Streaming (SSE)
• Integrazione server MCP
• Fatturazione
• Limiti di frequenza
• Gestione degli errori
• Paginazione
• Localizzazione
• Privacy e dati
• Supporto

Panoramica

Esegui agenti IA personalizzati nel tuo prodotto o workflow in pochi minuti. Configura i tuoi agenti per qualsiasi attività, scegli qualsiasi modello e strumento e lascia a Jenova la gestione di harness per agenti, database e scalabilità.

Lo stack completo per gli agenti:

• Harness per agenti gestito: Una chiamata in entrata, lavoro finito in uscita. Il tuo agente fa ricerche, ragiona, chiama gli strumenti e genera i file — esattamente come lo istruisci.
• Contesto e memoria senza limiti: La gestione del contesto basata su RAG e il tracciamento proprietario dello stato della sessione consentono una memoria illimitata all'interno delle conversazioni.
• Libreria di strumenti e MCP: Collegati alla nostra libreria di 30+ strumenti e server MCP, come ricerca, generazione di immagini, email e altro — oppure aggiungi i tuoi server MCP.
• Passa a qualsiasi modello senza attriti: Distribuisci modelli di OpenAI, Anthropic, Google, xAI o dei principali fornitori open source e passa da un modello all'altro con un solo parametro.
• Conoscenza e RAG gestiti: Jenova gestisce la pipeline RAG end-to-end — chunking, indicizzazione, archiviazione e recupero.
• Collaudata su larga scala: Distribuisci su un'infrastruttura testata sul campo che esegue centinaia di agenti attivi in produzione. Zero cluster da predisporre, scalare o mantenere.

Guida introduttiva

1. Ottenga la Sua chiave API

Generi una chiave API dal pannello di controllo per sviluppatori all'indirizzo www.jenova.ai/platform. Le chiavi utilizzano il formato jnv_sk_* e vengono passate come Bearer token.

2. Scelga o crei un Agente

Scelga un agente predefinito dalla piattaforma, oppure crei un agente personalizzato nel pannello di controllo con istruzioni, impostazioni del modello, file della base di conoscenza, strumenti e server MCP.

3. Invii il Suo primo Messaggio

Crei una sessione e invii un messaggio in un'unica chiamata:

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 risposta viene trasmessa in streaming come 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"}}

Acquisisca session_id da stream_started per le richieste successive. Per le risposte JSON sincrone, veda Invia Messaggio.

Concetti fondamentali

Agente

Un agente AI con cui interagisce tramite l'API. Ogni agente ha uno slug univoco (ad es. my-support-agent) utilizzato come valore agent nelle chiamate API.

• Predefinito: Selezioni tra gli agenti già esistenti sulla piattaforma.
• Personalizzato: Configuri il Suo agente nel pannello di controllo con istruzioni, modello, base di conoscenza, strumenti e server MCP.

Sessione

Un thread di conversazione indipendente tra un utente finale e un agente.

• Identificatore: ID con prefisso (ad es. ses_abc123).
• Ambito: Possono esistere più sessioni per lo stesso agente e utente finale, ciascuna con uno stato di conversazione indipendente.
• Ciclo di vita: Le sessioni persistono indefinitamente finché non vengono eliminate tramite API. Per attività one-shot che non richiedono una sessione, utilizzi POST /messages con ephemeral: true.
• Isolamento della piattaforma: Le sessioni API sono separate dalle conversazioni nell'app web di Jenova. Utenti finali, cronologia delle sessioni e fatturazione sono indipendenti tra l'API e l'app web.

Messaggio

Una singola voce nella cronologia di conversazione di una sessione, restituita dagli endpoint Messaggi. Ogni messaggio include un oggetto from strutturato con type (user o agent) e name, oltre a un type di messaggio:

• external - un messaggio di conversazione destinato a essere visualizzato come contenuto di chat.
• internal - un messaggio facoltativo che rappresenta i passaggi di lavoro dell'agente durante un'esecuzione, come chiamate a strumenti o recupero di informazioni.

Esecuzione

Una singola esecuzione dell'agente creata quando invia un messaggio. Un'esecuzione ha un run_id, può trasmettere eventi in streaming mentre è attiva e può produrre uno o più messaggi completati. Ogni sessione può avere solo un'esecuzione attiva alla volta.

Utente finale

Il campo user associa le sessioni a un utente finale nella Sua applicazione. Utilizzi un ID stabile e opaco, come il Suo ID utente interno o un UUID. Eviti indirizzi email o altri dati personali identificativi a meno che la Sua applicazione non li richieda. Le sessioni create con lo stesso valore user vengono raggruppate insieme, consentendo l'elenco delle sessioni per singolo utente.

Se user viene omesso, la sessione viene associata al Suo account sviluppatore e non potrà essere filtrata in seguito per utente finale. Passi user in produzione.

Per le richieste su sessioni esistenti (qualsiasi endpoint con {session_id} nel percorso), user è una protezione di proprietà facoltativa. Se lo fornisce, deve corrispondere al valore user utilizzato al momento della creazione della sessione; in caso contrario l'API restituisce 404 session_not_owned. Lo invii come parametro di query nelle richieste GET e DELETE, e nel corpo JSON nelle richieste POST e PATCH. Un parametro di query user su POST o PATCH restituisce 400 bad_request.

Autenticazione

Autentichi ogni richiesta con un Bearer token nell'header Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le chiavi API vengono generate dal pannello di controllo per sviluppatori.

User-Agent è facoltativo. Gli SDK possono impostarlo per finalità diagnostiche, ma l'API non lo richiede.

Formato della chiave: le chiavi iniziano con il prefisso jnv_sk_ seguito da una stringa casuale codificata in base62.

Limiti: ogni account sviluppatore può avere fino a 10 chiavi API attive.

Endpoint API

Messaggi

L'invio di Messaggi è il percorso API principale. Utilizzi POST /messages per il primo messaggio; questo crea la sessione e avvia l'esecuzione in un'unica richiesta. Utilizzi POST /sessions/{session_id}/messages per continuare una sessione di cui ha già acquisito il session_id.

Invia Messaggio

POST /messages

Crea una sessione persistente e invia il primo messaggio in un'unica richiesta. Imposti ephemeral: true per una richiesta one-shot in streaming che non restituisce un ID sessione e non può essere continuata. I suoi dati vengono eliminati poco dopo il completamento della richiesta.

Corpo della richiesta

Esempio - Streaming (predefinito)

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 risposta è uno stream SSE (per il formato degli eventi, vedere Streaming (SSE)). Le richieste persistenti includono il nuovo session_id; le richieste con ephemeral: true omettono session_id e devono utilizzare lo streaming.

Esempio - JSON (senza streaming)

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
  }'

Risposta

Le risposte in streaming emettono gli eventi SSE documentati in Streaming (SSE). Le risposte senza streaming restituiscono l'oggetto messaggio con stop_reason e usage per la richiesta, come mostrato in Continua Sessione. stop_reason è end_run, oppure user_cancelled se l'esecuzione è stata annullata dopo che l'agente ha prodotto un messaggio.

Se l'esecuzione viene annullata prima che l'agente produca un messaggio, l'API restituisce 200 OK con status: "cancelled", session_id, run_id, stop_reason: "user_cancelled" e usage.

Se un'esecuzione senza streaming è ancora in elaborazione dopo 90 secondi, l'API restituisce 202 Accepted con status: "processing", session_id, run_id e un message in testo leggibile. L'esecuzione continua dopo la risposta o la disconnessione del client; verifichi i messaggi della sessione, oppure utilizzi lo streaming per i flussi di lavoro più lunghi.

Errori

Continua Sessione

POST /sessions/{session_id}/messages

Invia un Messaggio a una Sessione persistente esistente e riceve la risposta dell'agente. Per impostazione predefinita, le risposte sono trasmesse in streaming tramite SSE; impostare stream: false per JSON.

Corpo della richiesta

Esempio - Streaming (predefinito)

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?"
  }'

Esempio - JSON (senza streaming)

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
  }'

Risposta 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"
  }
}

Se la Sessione ha già un'Esecuzione attiva o Messaggi in coda, l'API restituisce JSON 202 Accepted con status: "queued", session_id, run_id e message_id. Il Messaggio dell'utente viene elaborato dall'Esecuzione attiva. Le richieste con additional_context restituiscono invece 409 busy.

Le risposte senza streaming seguono le stesse regole di Invia Messaggio, inclusa la risposta status: "cancelled" quando l'Esecuzione viene annullata prima che l'Agente produca un Messaggio.

Errori

Idempotenza

POST /messages, POST /sessions/{session_id}/messages e POST /invoke accettano un header opzionale Idempotency-Key (max 255 caratteri). Utilizzi una chiave univoca per ogni invio logico dell'utente, in modo che i nuovi tentativi di rete o i doppi invii non creino esecuzioni duplicate. Le chiavi vengono conservate per 24 ore.

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"
  }'

Non in streaming: Ripetere la richiesta restituisce la risposta salvata con l'header Idempotent-Replayed: true, compresi gli errori restituiti dopo l'avvio dell'elaborazione della richiesta. Una risposta 202 Accepted salvata viene riproposta invariata; utilizzi Ottieni stato Esecuzione o Elenca Messaggi per verificare il risultato. Le richieste rifiutate prima dell'avvio dell'elaborazione, come gli errori di convalida o di credito, non vengono salvate, quindi un nuovo tentativo viene valutato di nuovo.

Streaming: Lo stream non viene riprodotto. Per POST /messages e POST /sessions/{session_id}/messages, ripetere la richiesta mentre è in esecuzione o dopo il completamento restituisce un errore di idempotenza con il run_id originale e, per le richieste persistenti, il session_id. Per le richieste persistenti, utilizzi Ottieni stato Esecuzione per verificare un'esecuzione attiva, oppure Elenca Messaggi per recuperare i risultati persistiti. I risultati di POST /invoke in streaming non possono essere recuperati dopo la chiusura dello stream. I tentativi successivi di POST /invoke restituiscono l’id originale anziché run_id e session_id.

Esempio di nuovo tentativo su streaming completato:

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"
  }
}

Errori di idempotenza

Elenca Messaggi

GET /sessions/{session_id}/messages

Restituisce un elenco paginato dei messaggi della sessione. Per impostazione predefinita vengono restituiti solo i messaggi di conversazione external. La prima pagina contiene i messaggi più recenti; all'interno di ciascuna pagina, i messaggi sono in ordine cronologico (dal più vecchio al più recente). sequence è il numero d'ordine del messaggio all'interno della sessione.

Parametri di query

Esempio

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

Risposta 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",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Oggetto Messaggio

Oggetto File

Errori

Ottieni Messaggio

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

Recupera un singolo messaggio tramite ID.

Parametri di query

Risposta 200 OK

Restituisce un singolo oggetto messaggio con la stessa struttura della risposta dell'elenco.

Errori

Allegati file

Fornisca URL HTTPS pubblicamente accessibili nel campo file_urls.

Formati supportati

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

Gli URL dei file vengono recuperati quando l'agente li legge durante l'esecuzione, non quando la richiesta viene accettata. Un URL che non può essere recuperato, o un file superiore a 20 MB, non viene letto; la richiesta in sé non viene rifiutata.

Quando si elencano i messaggi, i file allegati compaiono nell'array files del messaggio.

Contesto aggiuntivo

Passi un contesto con nome per un singolo Messaggio in additional_context, ad esempio i dettagli dell'account dell'utente finale. Non viene salvato nello storico dei messaggi.

Utilizzi un nome descrittivo come customer_profile o order_details.

Un elemento con name o content mancante o non di tipo stringa restituisce 400 invalid_payload. Gli altri elementi non validi restituiscono 400 bad_request.

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?",
    "additional_context": [
      {
        "name": "customer_profile",
        "content": "Plan: Pro. Last login: 2026-05-18."
      }
    ]
  }'

Sessioni

Le sessioni sono conversazioni persistenti tra un utente finale e un agente. La maggior parte delle integrazioni può crearle implicitamente con POST /messages.

Crea Sessione

POST /sessions

Crea una sessione persistente vuota associata a un agente specifico. Utilizzi questo endpoint quando ha bisogno di un ID di sessione prima del primo messaggio; altrimenti preferisca POST /messages.

Nota: ephemeral non è accettato su POST /sessions; utilizzi POST /messages con ephemeral: true per richieste one-shot.

Corpo della richiesta

Esempio

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"
  }'

Risposta 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"
}

Oggetto Sessione

Errori

Elenca Sessioni

GET /sessions

Restituisce un elenco paginato delle Sue sessioni, ordinato per data di ultimo aggiornamento più recente.

Parametri di query

Esempio

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

Risposta 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": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Errori

Ottieni Sessione

GET /sessions/{session_id}

Recupera una singola sessione tramite ID.

Parametri di query

Risposta 200 OK

Restituisce un oggetto sessione.

Errori

Rinomina Sessione

PATCH /sessions/{session_id}

Aggiorna il nome visualizzato di una sessione.

Corpo della richiesta

Risposta 200 OK

Restituisce l'oggetto sessione aggiornato.

Errori

Elimina Sessione

DELETE /sessions/{session_id}

Elimina definitivamente una sessione e tutti i suoi messaggi. La sessione non deve avere un'esecuzione attiva.

Risposta 204 No Content

Errori

Operazioni

Questi endpoint sono controlli di ripristino e modifica per le sessioni persistenti. La maggior parte delle integrazioni necessita solo di Annulla Esecuzione attiva; utilizzi le altre operazioni quando desidera intenzionalmente modificare o ripristinare lo stato della sessione. Tutte le operazioni supportano il controllo facoltativo di proprietà user descritto in Utente finale.

Annulla Esecuzione attiva

POST /sessions/{session_id}/cancel

Annulla l'esecuzione attiva dell'agente. Questo non elimina i messaggi già completati prima dell'annullamento.

Corpo della richiesta

Risposta 204 No Content

Errori

Annulla e rimuovi l'Esecuzione attiva

POST /sessions/{session_id}/undo

Annulla l'esecuzione attiva, attende che si interrompa, quindi rimuove tutti i messaggi che aveva già aggiunto. Nessun output aggiuntivo viene salvato dopo l'emissione del comando di annullamento e rimozione.

Corpo della richiesta

Risposta 200 OK

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

Se l'esecuzione viene annullata prima che qualsiasi messaggio sia completato, deleted è un array vuoto.

Errori

Elimina Messaggi recenti

POST /sessions/{session_id}/messages/delete

Rimuove i count Messaggi più recenti da una Sessione inattiva, inclusi i Messaggi internal. Utilizzi include=all in Elenca Messaggi per visualizzarli. La Sessione non deve avere un'Esecuzione attiva.

Corpo della richiesta

Risposta 200 OK

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

Errori

Duplica Sessione

POST /sessions/{session_id}/fork

Crea una nuova Sessione copiando la Sessione di origine fino a un Messaggio specifico. La Sessione di origine non deve avere un'Esecuzione attiva.

Corpo della richiesta (facoltativo)

Risposta 201 Created

Restituisce l'oggetto Sessione appena creato, con la stessa struttura della creazione di una Sessione.

Errori

Ottieni stato Esecuzione

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

Restituisce lo stato attuale di un'Esecuzione attiva. Utilizzi questo endpoint dopo una connessione SSE interrotta o dopo una risposta di idempotenza che ha restituito un run_id. Al termine di un'Esecuzione, recuperi i risultati con GET /sessions/{session_id}/messages.

Risposta 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"
}

status è running mentre l'agente è al lavoro, streaming quando viene prodotto il testo della risposta, oppure ended per breve tempo dopo il termine dell'Esecuzione. La risposta può anche includere progress_events con l'attività recente, nello stesso formato di stream_progress. Quando status è ended o la richiesta restituisce 404 not_found, recuperi i messaggi della Sessione.

Errori

Crediti

Ottieni saldo

GET /credits/balance

Restituisce il Suo saldo Crediti attuale.

Risposta 200 OK

{
  "balance": "123.45"
}

Agenti

Crei e modifichi Agenti personalizzati nel Pannello di controllo. Il supporto API per la creazione e la modifica degli Agenti sarà disponibile a breve.

I flussi di lavoro pianificati/in background non sono attualmente supportati tramite l'API. Il supporto sarà disponibile a breve.

Elenca Agenti

GET /agents

Restituisce gli agenti disponibili per il Suo account. Utilizzi il valore agent quando crea Sessioni o invia messaggi.

Risposta 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"
    }
  ]
}

Modelli

Elenca Modelli

GET /models

Restituisce tutti i modelli disponibili per l'uso nel campo model durante l'invio dei Messaggi o la chiamata a POST /invoke.

Risposta 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": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-thinking"
    }
  ]
}

I Modelli con un thinking_variant supportano il ragionamento estesa. Utilizzi l'ID della variante direttamente nel campo model per attivarla.

Se non viene specificato alcun model durante l'invio di un Messaggio, viene utilizzato il model della sessione. Viene impostato sul Modello predefinito dell'Agente alla creazione della sessione.

Invoca Modello

POST /invoke

Invia un prompt direttamente a un Modello, senza agente, Sessione o strumenti. Per impostazione predefinita, le risposte sono trasmesse in streaming tramite SSE; impostare stream: false per JSON.

Corpo della richiesta

Esempio

curl -X POST https://api.jenova.ai/v1/invoke \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "content": "Describe a forest in one sentence.",
    "stream": false
  }'

Risposta 200 OK

{
  "id": "inv_abc123",
  "model": "claude-sonnet-5",
  "content": "Sunlight filters through tall pines onto a quiet, mossy floor.",
  "usage": {
    "cost": "0.0004"
  }
}

Le risposte in streaming inviano stream_started, poi eventi stream_delta mentre il modello genera il testo, e terminano con stream_ended, che include usage. Concateni i valori di chunk_content nell'ordine di seq per costruire la risposta in streaming. Se la richiesta non riesce, stream_error viene inviato prima di stream_ended. Gli eventi riportano id al posto di session_id e run_id.

usage.cost è null quando il costo non è disponibile. Se una richiesta non in streaming fallisce dopo l'avvio della chiamata al modello, la risposta di errore include i campi id e usage di primo livello.

Le richieste in streaming hanno un limite di 120 minuti. Le richieste non in streaming attendono il risultato fino a 30 minuti invece di restituire 202 Accepted, e restituiscono un errore se il risultato non è pronto entro quel tempo.

Errori

Documentazione

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

Restituisce questo riferimento in formato Markdown. Utilizzi lang per selezionare la lingua.

Streaming (SSE)

Quando stream viene omesso o impostato su true (valore predefinito), le risposte ai Messaggi vengono fornite come Server-Sent Events. Utilizzi gli Eventi message_completed per identificare i Messaggi pronti da recuperare o visualizzare.

Timeout: le connessioni SSE restano aperte fino al termine dell'Esecuzione. Le Esecuzioni hanno un limite di 120 minuti. Le richieste di messaggi non in Streaming attendono fino a 90 secondi, poi restituiscono 202 Accepted mentre l'Esecuzione continua. Per POST /invoke non in Streaming, consulti Invoca Modello.

Header di connessione

Gli stream dei messaggi impostano questi header:

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

X-Run-Id è disponibile prima del primo Evento SSE. Gli stream di POST /invoke non impostano X-Run-Id; utilizzi l'id in stream_started.

Riconnessione e ripristino

I flussi SSE non vengono riproposti. Se la connessione si interrompe su una richiesta persistente, utilizzi il session_id e il run_id acquisiti per ripristinare lo stato:

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

Se l'Esecuzione è ancora attiva, questo restituisce lo stato attuale, il testo parziale e i progressi recenti. Se restituisce status: "ended" o 404 not_found, l'Esecuzione non è più attiva; recuperi i messaggi della Sessione per riconciliare l'output completato:

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

Formato del frame

Ogni frame SSE segue il formato standard:

event: <event_type>
data: <json_payload>

Due caratteri di nuova riga terminano ogni frame.

Tipi di Evento

Gli stream includono eventi di ciclo di vita, delta di testo, pensiero, avanzamento, avviso, completamento messaggio, connessione MCP, errore, finale e ping. Alcuni tipi di evento vengono inviati solo quando pertinenti.

Per le richieste effimere (ephemeral: true), ogni Evento SSE omette session_id. Utilizzi run_id solo per correlare gli Eventi all'interno di quel singolo stream.

Per la riconciliazione finale sulle richieste persistenti, attenda stream_ended, quindi chiami Elenca Messaggi.

Campi comuni sugli Eventi con ambito Esecuzione:

stream_started

Inviato una volta all'avvio dell'Esecuzione.

stream_delta

Inviato ripetutamente mentre l'Agente genera testo di risposta visibile. Concateni i valori di chunk_content nell'ordine di seq per costruire la risposta in streaming.

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

stream_thinking

Inviato ripetutamente mentre l'Agente emette output di thinking. Utilizzi questo Evento per un indicatore di thinking separato o una visualizzazione di traccia; non lo concateni nel testo di risposta finale.

stream_progress

Segnala attività visibili all’utente durante la generazione, come la lettura di un documento, la ricerca sul web o l’attesa di un’azione dell’utente. Questi eventi sono pensati per una visualizzazione temporanea nell’interfaccia; ignori i campi sconosciuti. Usi i messaggi completati come cronologia dei messaggi autorevole.

Imposti include_progress: false in una richiesta di Messaggio per omettere solo stream_progress. Gli Eventi di ciclo di vita, ping, message_completed, gli errori e gli Eventi terminali vengono comunque inviati quando pertinenti.

Alcuni Eventi di avanzamento possono includere url, file_name o server_name come suggerimenti facoltativi per la visualizzazione.

message_completed

Inviato ogni volta che un Messaggio è completo e pronto per essere recuperato o visualizzato.

Questo è un marcatore di confine, non l'oggetto Messaggio completo. Recuperi il Messaggio se ha bisogno del contenuto o dei metadati.

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

mcp_connection

Inviato quando l’agente ha bisogno che l’utente finale connetta o autorizzi uno o più server MCP prima di poter continuare. Questo evento è disponibile solo in modalità streaming.

mcp_connection_resolved

Inviato quando l’azione utente di connessione MCP è stata risolta o è scaduta.

Nessun campo aggiuntivo oltre ai campi comuni con ambito Esecuzione.

warning

Inviato per avvisi non fatali durante un'Esecuzione.

stream_error

Inviato quando un'Esecuzione fallisce. Potrebbe seguire un Evento finale stream_ended con success: false e stop_reason: "error".

stream_ended

Inviato una volta quando l'esecuzione termina. Questo è l'evento finale dello stream.

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

Esempio di Esecuzione annullata:

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

ping

Frame di keepalive inviati ogni 15 secondi per evitare timeout di proxy/CDN. Ignorarli nel client.

Integrazione server MCP

Colleghi i Suoi Agenti a strumenti esterni tramite il Model Context Protocol (MCP):

• Server MCP gestiti da Jenova: server ospitati da Jenova per ricerca, recupero di contenuti, generazione di documenti e altre funzionalità integrate
• Server MCP remoti: altri server MCP remoti configurati per il Suo Agente

I server MCP devono essere configurati nel Pannello di controllo durante la creazione o la modifica del Suo Agente. Per utilizzare un proprio server MCP, lo aggiunga a un Agente personalizzato, quindi chiami tale Agente tramite l'API. L'API esegue gli Strumenti abilitati nella configurazione dell'Agente; non è richiesta alcuna configurazione aggiuntiva nelle richieste API.

Quando un Agente utilizza Strumenti MCP durante una risposta, gli Eventi di progresso vengono inviati nello stream nel momento in cui si verificano:

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

Se l’agente richiede che l’utente finale connetta o autorizzi un server MCP durante l’esecuzione, le risposte in streaming possono includere gli eventi mcp_connection e mcp_connection_resolved. Presenti l’elenco dei server da connettere al suo utente finale e apra l’auth_url fornito, quando presente. Mantenga aperto lo stream SSE mentre l’utente finale connette o autorizza il server.

Dopo l'autorizzazione, Jenova memorizza il token, la finestra di autorizzazione mostra una pagina di completamento e la stessa Esecuzione continua automaticamente. Non è necessario che l'Utente finale rinvii il Messaggio.

Se l’utente finale non connette, autorizza, oppure salta o silenzia prima di user_action_deadline_unix, l’esecuzione termina con stop_reason: "user_action_timeout". È inoltre possibile annullare l’esecuzione attiva con POST /sessions/{session_id}/cancel.

Memorizzi l’auth_url lato client. Se il client si disconnette durante l’autorizzazione, l’URL rimane valido fino a user_action_deadline_unix. Per le richieste persistenti, verifichi l’esecuzione con Ottieni stato Esecuzione oppure recuperi i messaggi dopo il termine dell’esecuzione.

Le richieste non in streaming (stream: false) non supportano azioni utente di connessione MCP; usi lo streaming per agenti che potrebbero richiedere questa interazione.

Saltare la connessione MCP

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

Ignora un’azione utente di connessione MCP in sospeso e consente all’esecuzione di continuare senza quella connessione.

Per silenziare le future richieste di connessione per un server per lo stesso utente finale e agente, includa mcp_server_id e mute. mute accetta una durata come 30m, 24h o 7d, oppure forever.

Corpo della richiesta

Risposta 204 No Content

Lo stream emette mcp_connection_resolved, quindi l’esecuzione continua con lo stesso run_id.

Errori

Fatturazione

Tutti i costi vengono detratti dal Suo saldo di Crediti sviluppatore. Consulti l'Utilizzo e ricarichi i Crediti su www.jenova.ai/platform.

Prezzi

Il costo del Messaggio dipende da:

• Modello - Modelli diversi hanno costi per token diversi
• Lunghezza del contesto - Sessioni più lunghe consumano più token di input per richiesta
• Complessità del workflow - workflow più lunghi e un uso più intenso degli Strumenti (ricerca web, generazione di file, analisi di documenti) aumentano il consumo totale di token

Il costo effettivo viene restituito come stream_ended.usage.cost per le richieste in Streaming e come usage.cost per le richieste JSON non in Streaming.

Blocchi crediti

Ogni richiesta POST /messages, POST /sessions/{session_id}/messages e POST /invoke applica un blocco di $0,50 sul Suo saldo Crediti prima dell'inizio dell'esecuzione. Questo riserva i fondi per la richiesta. Un Messaggio in coda in un'Esecuzione attiva (202 Accepted con status: "queued") non crea un blocco aggiuntivo; l'Utilizzo dell'Esecuzione attiva viene verificato rispetto al Suo saldo residuo.

Al termine della richiesta, il blocco viene liquidato in base al costo effettivo e la differenza viene rilasciata. Se il costo effettivo supera il blocco, viene addebitata anche la differenza, quindi il Suo saldo può scendere sotto zero. Le richieste annullate o non riuscite vengono addebitate solo per l'Utilizzo già maturato. Se una richiesta fallisce prima di raggiungere il Modello, il blocco completo viene rilasciato.

A causa dei blocchi, il Suo saldo disponibile potrebbe apparire temporaneamente inferiore durante le richieste in corso. È necessario disporre di almeno $0,50 di saldo disponibile per una richiesta POST /sessions/{session_id}/messages, POST /messages effimera o POST /invoke. Una richiesta POST /messages persistente crea anche una Sessione e richiede almeno $0,51 per coprire il blocco più la commissione di creazione della Sessione.

Limiti di frequenza

Ogni account sviluppatore è soggetto a tre dimensioni di Limite di frequenza:

Un'esecuzione mantiene il proprio slot concorrente fino al termine, anche dopo una risposta 202 Accepted o la disconnessione del client. Una richiesta POST /invoke mantiene il proprio slot fino al completamento, anche se il client si disconnette.

Le richieste GET e HEAD non consumano slot concorrenti. cancel, undo e mcp/connection/skip non consumano slot concorrenti, quindi queste operazioni rimangono disponibili quando tutti gli slot sono in uso. Queste richieste continuano comunque a conteggiare per RPM e RPD.

Si applica inoltre a tutte le richieste un limite separato per IP di 1.200 richieste ogni 60 secondi, che restituisce lo stesso errore 429 rate_limit_exceeded.

Header di risposta

Le risposte API autenticate includono header relativi al limite di frequenza:

Quando viene superato il limite giornaliero, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset descrivono invece la finestra giornaliera.

Quando un limite viene superato, l'API restituisce 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Gestione degli errori

Gli errori HTTP immediati e gli errori di esecuzione non in streaming seguono una struttura coerente:

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

I messaggi di errore sono localizzati in base a lang o Accept-Language (vedere Localizzazione).

Gli errori di Esecuzione in streaming vengono trasmessi come Eventi stream_error. Un'Esecuzione non riuscita può comunque inviare un Evento finale stream_ended con success: false e stop_reason impostato. Gli errori di Esecuzione non in streaming includono un oggetto usage di primo livello; cost è null quando il costo non è disponibile.

Questi errori possono verificarsi su qualsiasi endpoint:

Gli errori specifici di ciascun endpoint sono documentati direttamente nella relativa sezione.

Errori di Esecuzione dopo l'avvio

Gli errori di Esecuzione emergono dopo che una richiesta di Messaggio è stata accettata. In modalità streaming, appaiono come Eventi stream_error e possono essere seguiti da stream_ended con success: false. In modalità non streaming, vengono restituiti come risposta di errore JSON con il codice di stato HTTP indicato di seguito.

Paginazione

Elenca Sessioni ed Elenca Messaggi utilizzano la paginazione basata su cursore:

{
  "items": [],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Passi next_cursor come parametro di query cursor per recuperare la pagina successiva, codificando il valore per l'URL. Quando has_more è false, non ci sono ulteriori risultati. Un limit al di fuori dell'intervallo 1-100 o un cursore non valido restituisce 400 bad_request.

Localizzazione

Tutti gli endpoint accettano un parametro di query facoltativo lang per controllare la lingua dei messaggi di errore e di qualsiasi contenuto localizzato.

Può aggiungere ?lang=xx a qualsiasi URL di richiesta:

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

Lingue supportate: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Privacy e dati

Jenova non utilizza i prompt API, gli output, la cronologia delle conversazioni, i file caricati, le istruzioni degli Agenti o le Basi di conoscenza per addestrare i modelli Jenova.

Per quanto riguarda i provider di Modelli terzi, Jenova utilizza canali API commerciali, impostazioni dell'account, impegni contrattuali o meccanismi di opt-out volti a impedire che i contenuti dei clienti vengano utilizzati per addestrare i Modelli dei provider.

Jenova archivia ed elabora i dati API utilizzando infrastrutture statunitensi. I provider terzi possono elaborare i dati in altre giurisdizioni, come descritto nell'Informativa sulla privacy e nei Termini di utilizzo.

Per maggiori dettagli, consulti i Termini di utilizzo, l'Informativa sulla privacy e la Politica di utilizzo.

Supporto

• Pannello di controllo: www.jenova.ai/platform
• Email: [email protected]